We've been using XML for ages.
+++ /dev/null
-<?xml version="1.0"?>
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
- "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
-]>
-<refentry id="gtk-building">
-<refmeta>
-<refentrytitle>Compiling the GTK libraries</refentrytitle>
-<manvolnum>3</manvolnum>
-<refmiscinfo>GTK Library</refmiscinfo>
-</refmeta>
-
-<refnamediv>
-<refname>Compiling the GTK Libraries</refname>
-<refpurpose>
-How to compile GTK itself
-</refpurpose>
-</refnamediv>
- <refsect1 id="overview">
- <title>Building GTK</title>
- <para>
- Before we get into the details of how to compile GTK, we should
- mention that in many cases, binary packages of GTK prebuilt for
- your operating system will be available, either from your
- operating system vendor or from independent sources. If such a
- set of packages is available, installing it will get you
- programming with GTK much faster than building it yourself. In
- fact, you may well already have GTK installed on your system
- already.
- </para>
- <para>
- In order to build GTK, you will need <application>meson</application>
- installed on your system. On Linux, and other UNIX-like operating
- systems, you will also need <application>ninja</application>. This
- guide does not cover how to install these two requirements, but you
- can refer to the <ulink url="http://mesonbuild.com">Meson website</ulink>
- for more information. The <ulink url="https://ninja-build.org">Ninja</ulink>
- build tool is also usable on various operating systems, so we will
- refer to it in the examples.
- </para>
- <para>
- If you are building GTK from a source distribution or from a Git
- clone, you will need to use <application>meson</application> to
- configure the project. The most commonly useful argument is the
- <systemitem>--prefix</systemitem> one, which determines where the
- files will go once installed. To install GTK under a prefix
- like <filename>/opt/gtk</filename> you would run Meson as:
- </para>
- <informalexample>
- <programlisting>
- meson --prefix /opt/gtk builddir
- </programlisting>
- </informalexample>
- <para>
- Meson will create the <filename>builddir</filename> directory and
- place all the build artefacts there.
- </para>
- <para>
- You can get a list of all available options for the build by
- running <application>meson configure</application>.
- </para>
- <para>
- After Meson successfully configured the build directory, you then
- can run the build, using Ninja:
- </para>
- <informalexample>
- <programlisting>
- cd builddir
- ninja
- ninja install
- </programlisting>
- </informalexample>
- <para>
- If you don't have permission to write to the directory you are
- installing in, you may have to change to root temporarily before
- running <literal>ninja install</literal>.
- </para>
- <para>
- Several environment variables are useful to pass to set before
- running <application>meson</application>. <envar>CPPFLAGS</envar>
- contains options to pass to the C compiler, and is used to tell
- the compiler where to look for include files. The <envar>LDFLAGS</envar>
- variable is used in a similar fashion for the linker. Finally the
- <envar>PKG_CONFIG_PATH</envar> environment variable contains
- a search path that <command>pkg-config</command> (see below)
- uses when looking for files describing how to compile
- programs using different libraries. If you were installing GTK
- and it's dependencies into <filename>/opt/gtk</filename>, you
- might want to set these variables as:
- </para>
- <programlisting>
- CPPFLAGS="-I/opt/gtk/include"
- LDFLAGS="-L/opt/gtk/lib"
- PKG_CONFIG_PATH="/opt/gtk/lib/pkgconfig"
- export CPPFLAGS LDFLAGS PKG_CONFIG_PATH
- </programlisting>
- <para>
- You may also need to set the <envar>LD_LIBRARY_PATH</envar>
- environment variable so the systems dynamic linker can find
- the newly installed libraries, and the <envar>PATH</envar>
- environment program so that utility binaries installed by
- the various libraries will be found.
- </para>
- <programlisting>
- LD_LIBRARY_PATH="/opt/gtk/lib"
- PATH="/opt/gtk/bin:$PATH"
- export LD_LIBRARY_PATH PATH
- </programlisting>
- </refsect1>
-
- <refsect1 id="build-types">
- <title>Build types</title>
-
- <para>Meson has different build types, exposed by the <literal>buildtype</literal>
- configuration option. GTK enables and disables functionality depending on
- the build type used when calling <application>meson</application> to
- configure the build.</para>
-
- <formalpara>
- <title><systemitem>debug</systemitem> and <systemitem>debugoptimized</systemitem></title>
-
- <para>
- GTK will enable debugging code paths in both the
- <literal>debug</literal> and <literal>debugoptimized</literal>
- build types. Builds with <literal>buildtype</literal> set
- to <literal>debug</literal> will additionally enable
- consistency checks on the internal state of the toolkit.
- </para>
-
- <para>
- It is recommended to use the <literal>debug</literal> or
- <literal>debugoptimized</literal> build types when developing
- GTK itself. Additionally, <literal>debug</literal> builds of
- GTK are recommended for profiling and debugging GTK applications,
- as they include additional validation of the internal state.
- </para>
-
- <para>
- The <literal>debugoptimized</literal> build type is the
- default for GTK if no build type is specified when calling
- <application>meson</application>
- </para>
- </formalpara>
-
- <formalpara>
- <title><systemitem>release</systemitem></title>
-
- <para>
- The <literal>release</literal> build type will disable
- debugging code paths and additional run time safeties, like
- checked casts for object instances.
- </para>
- </formalpara>
-
- <para>
- The <literal>plain</literal> build type provided by Meson
- should only be used when packaging GTK, and it's expected
- that packagers will provide their own compiler flags when
- building GTK. See the previous section for the list of
- environment variables to be used to define compiler and
- linker flags.
- </para>
- </refsect1>
-
- <refsect1 id="dependencies">
- <title>Dependencies</title>
- <para>
- Before you can compile the GTK widget toolkit, you need to have
- various other tools and libraries installed on your
- system. Dependencies of GTK have their own build systems, so
- you will need to refer to their own installation instructions.
- </para>
- <para>
- A particular important tool used by GTK to find its dependencies
- is <application>pkg-config</application>.
- </para>
- <para>
- <ulink url="https://www.freedesktop.org/wiki/Software/pkg-config/">pkg-config</ulink>
- is a tool for tracking the compilation flags needed for
- libraries that are used by the GTK libraries. (For each
- library, a small <literal>.pc</literal> text file is installed
- in a standard location that contains the compilation flags
- needed for that library along with version number information.)
- </para>
- <para>
- Some of the libraries that GTK depends on are maintained by
- by the GTK team: GLib, GdkPixbuf, Pango, ATK and GObject Introspection.
- Other libraries are maintained separately.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- The GLib library provides core non-graphical functionality
- such as high level data types, Unicode manipulation, and
- an object and type system to C programs. It is available
- from <ulink url="https://download.gnome.org/sources/glib/">here</ulink>.
- </para>
- </listitem>
- <listitem>
- <para>
- The <ulink url="https://git.gnome.org/browse/gdk-pixbuf/">GdkPixbuf library</ulink>
- provides facilities for loading images in a variety of file formats.
- It is available <ulink url="https://download.gnome.org/sources/gdk-pixbuf/">here</ulink>.
- </para>
- </listitem>
- <listitem>
- <para>
- <ulink url="http://www.pango.org">Pango</ulink> is a library
- for internationalized text handling. It is available
- <ulink url="https://download.gnome.org/sources/pango/">here</ulink>.
- </para>
- </listitem>
- <listitem>
- <para>
- ATK is the Accessibility Toolkit. It provides a set of generic
- interfaces allowing accessibility technologies such as
- screen readers to interact with a graphical user interface.
- It is available
- <ulink url="https://download.gnome.org/sources/atk/">here</ulink>.
- </para>
- </listitem>
- <listitem>
- <para>
- <ulink url="https://wiki.gnome.org/Projects/GObjectIntrospection">Gobject Introspection</ulink>
- is a framework for making introspection data available to
- language bindings. It is available
- <ulink url="https://download.gnome.org/sources/gobject-introspection/">here</ulink>.
- </para>
- </listitem>
- </itemizedlist>
- <itemizedlist>
- <title>External dependencies</title>
- <listitem>
- <para>
- The <ulink url="https://www.gnu.org/software/libiconv/">GNU
- libiconv library</ulink> is needed to build GLib if your
- system doesn't have the <function>iconv()</function>
- function for doing conversion between character
- encodings. Most modern systems should have
- <function>iconv()</function>.
- </para>
- </listitem>
- <listitem>
- <para>
- The libintl library from the <ulink
- url="https://www.gnu.org/software/gettext/">GNU gettext
- package</ulink> is needed if your system doesn't have the
- <function>gettext()</function> functionality for handling
- message translation databases.
- </para>
- </listitem>
- <listitem>
- <para>
- The libraries from the X window system are needed to build
- Pango and GTK. You should already have these installed on
- your system, but it's possible that you'll need to install
- the development environment for these libraries that your
- operating system vendor provides.
- </para>
- </listitem>
- <listitem>
- <para>
- The <ulink url="https://www.freedesktop.org/wiki/Software/fontconfig/">fontconfig</ulink>
- library provides Pango with a standard way of locating
- fonts and matching them against font names.
- </para>
- </listitem>
- <listitem>
- <para>
- <ulink url="https://www.cairographics.org">Cairo</ulink>
- is a graphics library that supports vector graphics and image
- compositing. Both Pango and GTK use Cairo for drawing.
- </para>
- </listitem>
- <listitem>
- <para>
- <ulink url="https://github.com/anholt/libepoxy">libepoxy</ulink>
- is a library that abstracts the differences between different
- OpenGL libraries. GTK uses it for cross-platform GL support
- and for its own drawing.
- </para>
- </listitem>
- <listitem>
- <para>
- <ulink url="https://github.com/anholt/libepoxy">Graphene</ulink>
- is a library that provides vector and matrix types for 2D and
- 3D transformations. GTK uses it internally for drawing.
- </para>
- </listitem>
- <listitem>
- <para>
- The <ulink url="https://wayland.freedesktop.org">Wayland</ulink> libraries
- are needed to build GTK with the Wayland backend.
- </para>
- </listitem>
- <listitem>
- <para>
- The <ulink url="https://www.freedesktop.org/wiki/Software/shared-mime-info">shared-mime-info</ulink>
- package is not a hard dependency of GTK, but it contains definitions
- for mime types that are used by GIO and, indirectly, by GTK.
- gdk-pixbuf will use GIO for mime type detection if possible. For this
- to work, shared-mime-info needs to be installed and
- <envar>XDG_DATA_DIRS</envar> set accordingly at configure time.
- Otherwise, gdk-pixbuf falls back to its built-in mime type detection.
- </para>
- </listitem>
- </itemizedlist>
- </refsect1>
- <refsect1 id="building">
- <title>Building and testing GTK</title>
- <para>
- First make sure that you have the necessary external
- dependencies installed: <command>pkg-config</command>, Meson, Ninja,
- the JPEG, PNG, and TIFF libraries, FreeType, and, if necessary,
- libiconv and libintl. To get detailed information about building
- these packages, see the documentation provided with the
- individual packages. On any average Linux system, it's quite likely
- you'll have all of these installed already, or they will be easily
- accessible through your operating system package repositories.
- </para>
- <para>
- Then build and install the GTK libraries in the order:
- GLib, Cairo, Pango, ATK, then GTK. For each library, follow the
- instructions they provide, and make sure to share common settings
- between them and the GTK build; if you are using a separate prefix
- for GTK, for instance, you will need to use the same prefix for all
- its dependencies you build. If you're lucky, this will all go smoothly,
- and you'll be ready to <link linkend="gtk-compiling">start compiling
- your own GTK applications</link>. You can test your GTK installation
- by running the <command>gtk4-demo</command> program that
- GTK installs.
- </para>
- <para>
- If one of the projects you're configuring or building fails, look
- closely at the error messages printed; these will often provide useful
- information as to what went wrong. Every build system has its own
- log that can help you understand the issue you're encountering. If all
- else fails, you can ask for help on the gtk-list mailing list.
- See <xref linkend="gtk-resources"/> for more information.
- </para>
- </refsect1>
-
- <refsect1 id="extra-configuration-options">
- <title>Extra Configuration Options</title>
-
- <para>
- In addition to the normal options provided by Meson, GTK defines
- various arguments that modify what should be built.
-
- <cmdsynopsis>
- <command>meson</command>
- <sbr/>
- <group>
- <arg choice="plain">-Dx11-backend=true</arg>
- <arg choice="plain">-Dx11-backend=false</arg>
- </group>
- <sbr/>
- <group>
- <arg choice="plain">-Dwayland-backend=true</arg>
- <arg choice="plain">-Dwayland-backend=false</arg>
- </group>
- <sbr/>
- <group>
- <arg choice="plain">-Dbroadway-backend=true</arg>
- <arg choice="plain">-Dbroadway-backend=false</arg>
- </group>
- <sbr/>
- <group>
- <arg choice="plain">-Dwin32-backend=true</arg>
- <arg choice="plain">-Dwin32-backend=false</arg>
- </group>
- <sbr/>
- <group>
- <arg choice="plain">-Dquartz-backend=true</arg>
- <arg choice="plain">-Dquartz-backend=false</arg>
- </group>
- <sbr/>
- <group>
- <arg choice="plain">-Dmedia=gstreamer</arg>
- <arg choice="plain">-Dmedia=ffmpeg</arg>
- <arg choice="plain">-Dmedia=all</arg>
- <arg choice="plain">-Dmedia=none</arg>
- </group>
- <sbr/>
- <group>
- <arg choice="plain">-Dvulkan=yes</arg>
- <arg choice="plain">-Dvulkan=no</arg>
- <arg choice="plain">-Dvulkan=auto</arg>
- </group>
- <sbr/>
- <group>
- <arg choice="plain">-Dxinerama=yes</arg>
- <arg choice="plain">-Dxinerama=no</arg>
- <arg choice="plain">-Dxinerama=auto</arg>
- </group>
- <sbr/>
- <group>
- <arg choice="plain">-Dcloudproviders=true</arg>
- <arg choice="plain">-Dcloudproviders=false</arg>
- </group>
- <sbr/>
- <group>
- <arg choice="plain">-Dprint-backends=all</arg>
- <arg choice="plain">-Dprint-backends=none</arg>
- <arg choice="plain">-Dprint-backends=cups,lpr,...</arg>
- </group>
- <sbr/>
- <group>
- <arg choice="plain">-Dcolord=yes</arg>
- <arg choice="plain">-Dcolord=no</arg>
- <arg choice="plain">-Dcolord=auto</arg>
- </group>
- <sbr/>
- <group>
- <arg choice="plain">-Dgtk_doc=true</arg>
- <arg choice="plain">-Dgtk_doc=false</arg>
- </group>
- <sbr/>
- <group>
- <arg choice="plain">-Dman-pages=true</arg>
- <arg choice="plain">-Dman-pages=false</arg>
- </group>
- <sbr/>
- <group>
- <arg choice="plain">-Dintrospection=true</arg>
- <arg choice="plain">-Dintrospection=false</arg>
- </group>
- </cmdsynopsis>
- </para>
-
- <formalpara>
- <title><systemitem>xinerama</systemitem></title>
-
- <para>
- By default GTK will try to link against the Xinerama libraries
- if they are found. This options can be used to explicitly control
- whether Xinerama should be used.
- </para>
- </formalpara>
-
- <formalpara>
- <title><systemitem>gtk_doc</systemitem> and
- <systemitem>man-pages</systemitem></title>
-
- <para>
- The <application>gtk-doc</application> package is
- used to generate the reference documentation included
- with GTK. By default support for <application>gtk-doc</application>
- is disabled because it requires various extra dependencies
- to be installed. If you have
- <application>gtk-doc</application> installed and
- are modifying GTK, you may want to enable
- <application>gtk-doc</application> support by passing
- in <systemitem>gtk_doc</systemitem>.
- </para>
- <para>
- Additionally, some tools provided by GTK have their own
- manual pages generated using a similar set of dependencies;
- if you have <application>xsltproc</application> then you
- can generate manual pages by passing <systemitem>man-pages</systemitem>
- when configuring the build.
- </para>
- </formalpara>
-
- <formalpara>
- <title><systemitem>print-backends</systemitem></title>
-
- <para>
- By default, GTK will try to build various print backends if
- their dependencies are found. This option can be used to
- explicitly control which print backends should be built.
- </para>
- </formalpara>
-
- <formalpara>
- <title><systemitem>x11-backend</systemitem>,
- <systemitem>win32-backend</systemitem>,
- <systemitem>quartz-backend</systemitem>,
- <systemitem>broadway-backend</systemitem> and
- <systemitem>wayland-backend</systemitem></title>
-
- <para>
- Enable specific backends for GDK. If none of these options
- are given, the Wayland backend will be enabled by default,
- if the platform is Linux; the X11 backend will also be enabled
- by default, unless the platform is Windows, in which case the
- default is win32, or the platform is macOS, in which case the
- default is quartz. If any backend is explicitly enabled or disabled,
- no other platform will be enabled automatically.
- </para>
- </formalpara>
-
- <formalpara>
- <title><systemitem>introspection</systemitem></title>
-
- <para>
- Allows to disable building introspection support. This is option
- is mainly useful for shortening turnaround times on developer
- systems. Installed builds of GTK should always have introspection
- support.
- </para>
- </formalpara>
-
- <formalpara>
- <title><systemitem>build-tests</systemitem>,
- <systemitem>install-tests</systemitem>,
- <systemitem>demos</systemitem></title>
-
- <para>
- By default, GTK will build quite a few tests and demos.
- While these are useful on a developer system, they are not
- needed when GTK is built e.g. for a flatpak runtime. These
- options allow to disable building tests and demos.
- </para>
- </formalpara>
-
- </refsect1>
-
-</refentry>
-
-<!-- Local Variables: -->
-<!-- sgml-parent-document: ("gtk-docs.sgml" "chapter" "refentry") -->
-<!-- End: -->
--- /dev/null
+<?xml version="1.0"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
+]>
+<refentry id="gtk-building">
+<refmeta>
+<refentrytitle>Compiling the GTK libraries</refentrytitle>
+<manvolnum>3</manvolnum>
+<refmiscinfo>GTK Library</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+<refname>Compiling the GTK Libraries</refname>
+<refpurpose>
+How to compile GTK itself
+</refpurpose>
+</refnamediv>
+ <refsect1 id="overview">
+ <title>Building GTK</title>
+ <para>
+ Before we get into the details of how to compile GTK, we should
+ mention that in many cases, binary packages of GTK prebuilt for
+ your operating system will be available, either from your
+ operating system vendor or from independent sources. If such a
+ set of packages is available, installing it will get you
+ programming with GTK much faster than building it yourself. In
+ fact, you may well already have GTK installed on your system
+ already.
+ </para>
+ <para>
+ In order to build GTK, you will need <application>meson</application>
+ installed on your system. On Linux, and other UNIX-like operating
+ systems, you will also need <application>ninja</application>. This
+ guide does not cover how to install these two requirements, but you
+ can refer to the <ulink url="http://mesonbuild.com">Meson website</ulink>
+ for more information. The <ulink url="https://ninja-build.org">Ninja</ulink>
+ build tool is also usable on various operating systems, so we will
+ refer to it in the examples.
+ </para>
+ <para>
+ If you are building GTK from a source distribution or from a Git
+ clone, you will need to use <application>meson</application> to
+ configure the project. The most commonly useful argument is the
+ <systemitem>--prefix</systemitem> one, which determines where the
+ files will go once installed. To install GTK under a prefix
+ like <filename>/opt/gtk</filename> you would run Meson as:
+ </para>
+ <informalexample>
+ <programlisting>
+ meson --prefix /opt/gtk builddir
+ </programlisting>
+ </informalexample>
+ <para>
+ Meson will create the <filename>builddir</filename> directory and
+ place all the build artefacts there.
+ </para>
+ <para>
+ You can get a list of all available options for the build by
+ running <application>meson configure</application>.
+ </para>
+ <para>
+ After Meson successfully configured the build directory, you then
+ can run the build, using Ninja:
+ </para>
+ <informalexample>
+ <programlisting>
+ cd builddir
+ ninja
+ ninja install
+ </programlisting>
+ </informalexample>
+ <para>
+ If you don't have permission to write to the directory you are
+ installing in, you may have to change to root temporarily before
+ running <literal>ninja install</literal>.
+ </para>
+ <para>
+ Several environment variables are useful to pass to set before
+ running <application>meson</application>. <envar>CPPFLAGS</envar>
+ contains options to pass to the C compiler, and is used to tell
+ the compiler where to look for include files. The <envar>LDFLAGS</envar>
+ variable is used in a similar fashion for the linker. Finally the
+ <envar>PKG_CONFIG_PATH</envar> environment variable contains
+ a search path that <command>pkg-config</command> (see below)
+ uses when looking for files describing how to compile
+ programs using different libraries. If you were installing GTK
+ and it's dependencies into <filename>/opt/gtk</filename>, you
+ might want to set these variables as:
+ </para>
+ <programlisting>
+ CPPFLAGS="-I/opt/gtk/include"
+ LDFLAGS="-L/opt/gtk/lib"
+ PKG_CONFIG_PATH="/opt/gtk/lib/pkgconfig"
+ export CPPFLAGS LDFLAGS PKG_CONFIG_PATH
+ </programlisting>
+ <para>
+ You may also need to set the <envar>LD_LIBRARY_PATH</envar>
+ environment variable so the systems dynamic linker can find
+ the newly installed libraries, and the <envar>PATH</envar>
+ environment program so that utility binaries installed by
+ the various libraries will be found.
+ </para>
+ <programlisting>
+ LD_LIBRARY_PATH="/opt/gtk/lib"
+ PATH="/opt/gtk/bin:$PATH"
+ export LD_LIBRARY_PATH PATH
+ </programlisting>
+ </refsect1>
+
+ <refsect1 id="build-types">
+ <title>Build types</title>
+
+ <para>Meson has different build types, exposed by the <literal>buildtype</literal>
+ configuration option. GTK enables and disables functionality depending on
+ the build type used when calling <application>meson</application> to
+ configure the build.</para>
+
+ <formalpara>
+ <title><systemitem>debug</systemitem> and <systemitem>debugoptimized</systemitem></title>
+
+ <para>
+ GTK will enable debugging code paths in both the
+ <literal>debug</literal> and <literal>debugoptimized</literal>
+ build types. Builds with <literal>buildtype</literal> set
+ to <literal>debug</literal> will additionally enable
+ consistency checks on the internal state of the toolkit.
+ </para>
+
+ <para>
+ It is recommended to use the <literal>debug</literal> or
+ <literal>debugoptimized</literal> build types when developing
+ GTK itself. Additionally, <literal>debug</literal> builds of
+ GTK are recommended for profiling and debugging GTK applications,
+ as they include additional validation of the internal state.
+ </para>
+
+ <para>
+ The <literal>debugoptimized</literal> build type is the
+ default for GTK if no build type is specified when calling
+ <application>meson</application>
+ </para>
+ </formalpara>
+
+ <formalpara>
+ <title><systemitem>release</systemitem></title>
+
+ <para>
+ The <literal>release</literal> build type will disable
+ debugging code paths and additional run time safeties, like
+ checked casts for object instances.
+ </para>
+ </formalpara>
+
+ <para>
+ The <literal>plain</literal> build type provided by Meson
+ should only be used when packaging GTK, and it's expected
+ that packagers will provide their own compiler flags when
+ building GTK. See the previous section for the list of
+ environment variables to be used to define compiler and
+ linker flags.
+ </para>
+ </refsect1>
+
+ <refsect1 id="dependencies">
+ <title>Dependencies</title>
+ <para>
+ Before you can compile the GTK widget toolkit, you need to have
+ various other tools and libraries installed on your
+ system. Dependencies of GTK have their own build systems, so
+ you will need to refer to their own installation instructions.
+ </para>
+ <para>
+ A particular important tool used by GTK to find its dependencies
+ is <application>pkg-config</application>.
+ </para>
+ <para>
+ <ulink url="https://www.freedesktop.org/wiki/Software/pkg-config/">pkg-config</ulink>
+ is a tool for tracking the compilation flags needed for
+ libraries that are used by the GTK libraries. (For each
+ library, a small <literal>.pc</literal> text file is installed
+ in a standard location that contains the compilation flags
+ needed for that library along with version number information.)
+ </para>
+ <para>
+ Some of the libraries that GTK depends on are maintained by
+ by the GTK team: GLib, GdkPixbuf, Pango, ATK and GObject Introspection.
+ Other libraries are maintained separately.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ The GLib library provides core non-graphical functionality
+ such as high level data types, Unicode manipulation, and
+ an object and type system to C programs. It is available
+ from <ulink url="https://download.gnome.org/sources/glib/">here</ulink>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <ulink url="https://git.gnome.org/browse/gdk-pixbuf/">GdkPixbuf library</ulink>
+ provides facilities for loading images in a variety of file formats.
+ It is available <ulink url="https://download.gnome.org/sources/gdk-pixbuf/">here</ulink>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink url="http://www.pango.org">Pango</ulink> is a library
+ for internationalized text handling. It is available
+ <ulink url="https://download.gnome.org/sources/pango/">here</ulink>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ ATK is the Accessibility Toolkit. It provides a set of generic
+ interfaces allowing accessibility technologies such as
+ screen readers to interact with a graphical user interface.
+ It is available
+ <ulink url="https://download.gnome.org/sources/atk/">here</ulink>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink url="https://wiki.gnome.org/Projects/GObjectIntrospection">Gobject Introspection</ulink>
+ is a framework for making introspection data available to
+ language bindings. It is available
+ <ulink url="https://download.gnome.org/sources/gobject-introspection/">here</ulink>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <itemizedlist>
+ <title>External dependencies</title>
+ <listitem>
+ <para>
+ The <ulink url="https://www.gnu.org/software/libiconv/">GNU
+ libiconv library</ulink> is needed to build GLib if your
+ system doesn't have the <function>iconv()</function>
+ function for doing conversion between character
+ encodings. Most modern systems should have
+ <function>iconv()</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The libintl library from the <ulink
+ url="https://www.gnu.org/software/gettext/">GNU gettext
+ package</ulink> is needed if your system doesn't have the
+ <function>gettext()</function> functionality for handling
+ message translation databases.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The libraries from the X window system are needed to build
+ Pango and GTK. You should already have these installed on
+ your system, but it's possible that you'll need to install
+ the development environment for these libraries that your
+ operating system vendor provides.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <ulink url="https://www.freedesktop.org/wiki/Software/fontconfig/">fontconfig</ulink>
+ library provides Pango with a standard way of locating
+ fonts and matching them against font names.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink url="https://www.cairographics.org">Cairo</ulink>
+ is a graphics library that supports vector graphics and image
+ compositing. Both Pango and GTK use Cairo for drawing.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink url="https://github.com/anholt/libepoxy">libepoxy</ulink>
+ is a library that abstracts the differences between different
+ OpenGL libraries. GTK uses it for cross-platform GL support
+ and for its own drawing.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink url="https://github.com/anholt/libepoxy">Graphene</ulink>
+ is a library that provides vector and matrix types for 2D and
+ 3D transformations. GTK uses it internally for drawing.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <ulink url="https://wayland.freedesktop.org">Wayland</ulink> libraries
+ are needed to build GTK with the Wayland backend.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <ulink url="https://www.freedesktop.org/wiki/Software/shared-mime-info">shared-mime-info</ulink>
+ package is not a hard dependency of GTK, but it contains definitions
+ for mime types that are used by GIO and, indirectly, by GTK.
+ gdk-pixbuf will use GIO for mime type detection if possible. For this
+ to work, shared-mime-info needs to be installed and
+ <envar>XDG_DATA_DIRS</envar> set accordingly at configure time.
+ Otherwise, gdk-pixbuf falls back to its built-in mime type detection.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </refsect1>
+ <refsect1 id="building">
+ <title>Building and testing GTK</title>
+ <para>
+ First make sure that you have the necessary external
+ dependencies installed: <command>pkg-config</command>, Meson, Ninja,
+ the JPEG, PNG, and TIFF libraries, FreeType, and, if necessary,
+ libiconv and libintl. To get detailed information about building
+ these packages, see the documentation provided with the
+ individual packages. On any average Linux system, it's quite likely
+ you'll have all of these installed already, or they will be easily
+ accessible through your operating system package repositories.
+ </para>
+ <para>
+ Then build and install the GTK libraries in the order:
+ GLib, Cairo, Pango, ATK, then GTK. For each library, follow the
+ instructions they provide, and make sure to share common settings
+ between them and the GTK build; if you are using a separate prefix
+ for GTK, for instance, you will need to use the same prefix for all
+ its dependencies you build. If you're lucky, this will all go smoothly,
+ and you'll be ready to <link linkend="gtk-compiling">start compiling
+ your own GTK applications</link>. You can test your GTK installation
+ by running the <command>gtk4-demo</command> program that
+ GTK installs.
+ </para>
+ <para>
+ If one of the projects you're configuring or building fails, look
+ closely at the error messages printed; these will often provide useful
+ information as to what went wrong. Every build system has its own
+ log that can help you understand the issue you're encountering. If all
+ else fails, you can ask for help on the gtk-list mailing list.
+ See <xref linkend="gtk-resources"/> for more information.
+ </para>
+ </refsect1>
+
+ <refsect1 id="extra-configuration-options">
+ <title>Extra Configuration Options</title>
+
+ <para>
+ In addition to the normal options provided by Meson, GTK defines
+ various arguments that modify what should be built.
+
+ <cmdsynopsis>
+ <command>meson</command>
+ <sbr/>
+ <group>
+ <arg choice="plain">-Dx11-backend=true</arg>
+ <arg choice="plain">-Dx11-backend=false</arg>
+ </group>
+ <sbr/>
+ <group>
+ <arg choice="plain">-Dwayland-backend=true</arg>
+ <arg choice="plain">-Dwayland-backend=false</arg>
+ </group>
+ <sbr/>
+ <group>
+ <arg choice="plain">-Dbroadway-backend=true</arg>
+ <arg choice="plain">-Dbroadway-backend=false</arg>
+ </group>
+ <sbr/>
+ <group>
+ <arg choice="plain">-Dwin32-backend=true</arg>
+ <arg choice="plain">-Dwin32-backend=false</arg>
+ </group>
+ <sbr/>
+ <group>
+ <arg choice="plain">-Dquartz-backend=true</arg>
+ <arg choice="plain">-Dquartz-backend=false</arg>
+ </group>
+ <sbr/>
+ <group>
+ <arg choice="plain">-Dmedia=gstreamer</arg>
+ <arg choice="plain">-Dmedia=ffmpeg</arg>
+ <arg choice="plain">-Dmedia=all</arg>
+ <arg choice="plain">-Dmedia=none</arg>
+ </group>
+ <sbr/>
+ <group>
+ <arg choice="plain">-Dvulkan=yes</arg>
+ <arg choice="plain">-Dvulkan=no</arg>
+ <arg choice="plain">-Dvulkan=auto</arg>
+ </group>
+ <sbr/>
+ <group>
+ <arg choice="plain">-Dxinerama=yes</arg>
+ <arg choice="plain">-Dxinerama=no</arg>
+ <arg choice="plain">-Dxinerama=auto</arg>
+ </group>
+ <sbr/>
+ <group>
+ <arg choice="plain">-Dcloudproviders=true</arg>
+ <arg choice="plain">-Dcloudproviders=false</arg>
+ </group>
+ <sbr/>
+ <group>
+ <arg choice="plain">-Dprint-backends=all</arg>
+ <arg choice="plain">-Dprint-backends=none</arg>
+ <arg choice="plain">-Dprint-backends=cups,lpr,...</arg>
+ </group>
+ <sbr/>
+ <group>
+ <arg choice="plain">-Dcolord=yes</arg>
+ <arg choice="plain">-Dcolord=no</arg>
+ <arg choice="plain">-Dcolord=auto</arg>
+ </group>
+ <sbr/>
+ <group>
+ <arg choice="plain">-Dgtk_doc=true</arg>
+ <arg choice="plain">-Dgtk_doc=false</arg>
+ </group>
+ <sbr/>
+ <group>
+ <arg choice="plain">-Dman-pages=true</arg>
+ <arg choice="plain">-Dman-pages=false</arg>
+ </group>
+ <sbr/>
+ <group>
+ <arg choice="plain">-Dintrospection=true</arg>
+ <arg choice="plain">-Dintrospection=false</arg>
+ </group>
+ </cmdsynopsis>
+ </para>
+
+ <formalpara>
+ <title><systemitem>xinerama</systemitem></title>
+
+ <para>
+ By default GTK will try to link against the Xinerama libraries
+ if they are found. This options can be used to explicitly control
+ whether Xinerama should be used.
+ </para>
+ </formalpara>
+
+ <formalpara>
+ <title><systemitem>gtk_doc</systemitem> and
+ <systemitem>man-pages</systemitem></title>
+
+ <para>
+ The <application>gtk-doc</application> package is
+ used to generate the reference documentation included
+ with GTK. By default support for <application>gtk-doc</application>
+ is disabled because it requires various extra dependencies
+ to be installed. If you have
+ <application>gtk-doc</application> installed and
+ are modifying GTK, you may want to enable
+ <application>gtk-doc</application> support by passing
+ in <systemitem>gtk_doc</systemitem>.
+ </para>
+ <para>
+ Additionally, some tools provided by GTK have their own
+ manual pages generated using a similar set of dependencies;
+ if you have <application>xsltproc</application> then you
+ can generate manual pages by passing <systemitem>man-pages</systemitem>
+ when configuring the build.
+ </para>
+ </formalpara>
+
+ <formalpara>
+ <title><systemitem>print-backends</systemitem></title>
+
+ <para>
+ By default, GTK will try to build various print backends if
+ their dependencies are found. This option can be used to
+ explicitly control which print backends should be built.
+ </para>
+ </formalpara>
+
+ <formalpara>
+ <title><systemitem>x11-backend</systemitem>,
+ <systemitem>win32-backend</systemitem>,
+ <systemitem>quartz-backend</systemitem>,
+ <systemitem>broadway-backend</systemitem> and
+ <systemitem>wayland-backend</systemitem></title>
+
+ <para>
+ Enable specific backends for GDK. If none of these options
+ are given, the Wayland backend will be enabled by default,
+ if the platform is Linux; the X11 backend will also be enabled
+ by default, unless the platform is Windows, in which case the
+ default is win32, or the platform is macOS, in which case the
+ default is quartz. If any backend is explicitly enabled or disabled,
+ no other platform will be enabled automatically.
+ </para>
+ </formalpara>
+
+ <formalpara>
+ <title><systemitem>introspection</systemitem></title>
+
+ <para>
+ Allows to disable building introspection support. This is option
+ is mainly useful for shortening turnaround times on developer
+ systems. Installed builds of GTK should always have introspection
+ support.
+ </para>
+ </formalpara>
+
+ <formalpara>
+ <title><systemitem>build-tests</systemitem>,
+ <systemitem>install-tests</systemitem>,
+ <systemitem>demos</systemitem></title>
+
+ <para>
+ By default, GTK will build quite a few tests and demos.
+ While these are useful on a developer system, they are not
+ needed when GTK is built e.g. for a flatpak runtime. These
+ options allow to disable building tests and demos.
+ </para>
+ </formalpara>
+
+ </refsect1>
+
+</refentry>
+++ /dev/null
-<?xml version="1.0"?>
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
- "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
-]>
-<refentry id="gtk-compiling">
-<refmeta>
-<refentrytitle>Compiling GTK Applications</refentrytitle>
-<manvolnum>3</manvolnum>
-<refmiscinfo>GTK Library</refmiscinfo>
-</refmeta>
-
-<refnamediv>
-<refname>Compiling GTK Applications</refname>
-<refpurpose>
-How to compile your GTK application
-</refpurpose>
-</refnamediv>
-
-<refsect1>
-<title>Compiling GTK Applications on UNIX</title>
-
-<para>
-To compile a GTK application, you need to tell the compiler where to
-find the GTK header files and libraries. This is done with the
-<literal>pkg-config</literal> utility.
-</para>
-<para>
-The following interactive shell session demonstrates how
-<literal>pkg-config</literal> is used (the actual output on
-your system may be different):
-<programlisting>
-$ pkg-config --cflags gtk4
- -pthread -I/usr/include/gtk-4.0 -I/usr/lib64/gtk-4.0/include -I/usr/include/atk-1.0 -I/usr/include/cairo -I/usr/include/pango-1.0 -I/usr/include/glib-2.0 -I/usr/lib64/glib-2.0/include -I/usr/include/pixman-1 -I/usr/include/freetype2 -I/usr/include/libpng12
-$ pkg-config --libs gtk4
- -pthread -lgtk-4 -lgdk-4 -latk-1.0 -lgio-2.0 -lpangoft2-1.0 -lgdk_pixbuf-2.0 -lpangocairo-1.0 -lcairo -lpango-1.0 -lfreetype -lfontconfig -lgobject-2.0 -lgmodule-2.0 -lgthread-2.0 -lrt -lglib-2.0
-</programlisting>
-</para>
-<para>
-The simplest way to compile a program is to use the "backticks"
-feature of the shell. If you enclose a command in backticks
-(<emphasis>not single quotes</emphasis>), then its output will be
-substituted into the command line before execution. So to compile
-a GTK Hello, World, you would type the following:
-<programlisting>
-$ cc `pkg-config --cflags gtk4` hello.c -o hello `pkg-config --libs gtk4`
-</programlisting>
-</para>
-
-<para>
-Deprecated GTK functions are annotated to make the compiler
-emit warnings when they are used (e.g. with gcc, you need to use
-the -Wdeprecated-declarations option). If these warnings are
-problematic, they can be turned off by defining the preprocessor
-symbol %GDK_DISABLE_DEPRECATION_WARNINGS by using the commandline
-option <literal>-DGDK_DISABLE_DEPRECATION_WARNINGS</literal>
-</para>
-
-<para>
-GTK deprecation annotations are versioned; by defining the
-macros %GDK_VERSION_MIN_REQUIRED and %GDK_VERSION_MAX_ALLOWED,
-you can specify the range of GTK versions whose API you want
-to use. APIs that were deprecated before or introduced after
-this range will trigger compiler warnings.
-</para>
-
-<para>
-Here is how you would compile hello.c if you want to allow it
-to use symbols that were not deprecated in 4.2:
-<programlisting>
-$ cc `pkg-config --cflags gtk4` -DGDK_VERSION_MIN_REQIRED=GDK_VERSION_4_2 hello.c -o hello `pkg-config --libs gtk4`
-</programlisting>
-</para>
-
-<para>
-And here is how you would compile hello.c if you don't want
-it to use any symbols that were introduced after 4.2:
-<programlisting>
-$ cc `pkg-config --cflags gtk4` -DGDK_VERSION_MAX_ALLOWED=GDK_VERSION_4_2 hello.c -o hello `pkg-config --libs gtk4`
-</programlisting>
-</para>
-
-<para>
-The older deprecation mechanism of hiding deprecated interfaces
-entirely from the compiler by using the preprocessor symbol
-GTK_DISABLE_DEPRECATED is still used for deprecated macros,
-enumeration values, etc. To detect uses of these in your code,
-use the commandline option <literal>-DGTK_DISABLE_DEPRECATED</literal>.
-There are similar symbols GDK_DISABLE_DEPRECATED,
-GDK_PIXBUF_DISABLE_DEPRECATED and G_DISABLE_DEPRECATED for GDK, GdkPixbuf and
-GLib.
-</para>
-
-</refsect1>
-</refentry>
--- /dev/null
+<?xml version="1.0"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
+]>
+<refentry id="gtk-compiling">
+<refmeta>
+<refentrytitle>Compiling GTK Applications</refentrytitle>
+<manvolnum>3</manvolnum>
+<refmiscinfo>GTK Library</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+<refname>Compiling GTK Applications</refname>
+<refpurpose>
+How to compile your GTK application
+</refpurpose>
+</refnamediv>
+
+<refsect1>
+<title>Compiling GTK Applications on UNIX</title>
+
+<para>
+To compile a GTK application, you need to tell the compiler where to
+find the GTK header files and libraries. This is done with the
+<literal>pkg-config</literal> utility.
+</para>
+<para>
+The following interactive shell session demonstrates how
+<literal>pkg-config</literal> is used (the actual output on
+your system may be different):
+<programlisting>
+$ pkg-config --cflags gtk4
+ -pthread -I/usr/include/gtk-4.0 -I/usr/lib64/gtk-4.0/include -I/usr/include/atk-1.0 -I/usr/include/cairo -I/usr/include/pango-1.0 -I/usr/include/glib-2.0 -I/usr/lib64/glib-2.0/include -I/usr/include/pixman-1 -I/usr/include/freetype2 -I/usr/include/libpng12
+$ pkg-config --libs gtk4
+ -pthread -lgtk-4 -lgdk-4 -latk-1.0 -lgio-2.0 -lpangoft2-1.0 -lgdk_pixbuf-2.0 -lpangocairo-1.0 -lcairo -lpango-1.0 -lfreetype -lfontconfig -lgobject-2.0 -lgmodule-2.0 -lgthread-2.0 -lrt -lglib-2.0
+</programlisting>
+</para>
+<para>
+The simplest way to compile a program is to use the "backticks"
+feature of the shell. If you enclose a command in backticks
+(<emphasis>not single quotes</emphasis>), then its output will be
+substituted into the command line before execution. So to compile
+a GTK Hello, World, you would type the following:
+<programlisting>
+$ cc `pkg-config --cflags gtk4` hello.c -o hello `pkg-config --libs gtk4`
+</programlisting>
+</para>
+
+<para>
+Deprecated GTK functions are annotated to make the compiler
+emit warnings when they are used (e.g. with gcc, you need to use
+the -Wdeprecated-declarations option). If these warnings are
+problematic, they can be turned off by defining the preprocessor
+symbol %GDK_DISABLE_DEPRECATION_WARNINGS by using the commandline
+option <literal>-DGDK_DISABLE_DEPRECATION_WARNINGS</literal>
+</para>
+
+<para>
+GTK deprecation annotations are versioned; by defining the
+macros %GDK_VERSION_MIN_REQUIRED and %GDK_VERSION_MAX_ALLOWED,
+you can specify the range of GTK versions whose API you want
+to use. APIs that were deprecated before or introduced after
+this range will trigger compiler warnings.
+</para>
+
+<para>
+Here is how you would compile hello.c if you want to allow it
+to use symbols that were not deprecated in 4.2:
+<programlisting>
+$ cc `pkg-config --cflags gtk4` -DGDK_VERSION_MIN_REQIRED=GDK_VERSION_4_2 hello.c -o hello `pkg-config --libs gtk4`
+</programlisting>
+</para>
+
+<para>
+And here is how you would compile hello.c if you don't want
+it to use any symbols that were introduced after 4.2:
+<programlisting>
+$ cc `pkg-config --cflags gtk4` -DGDK_VERSION_MAX_ALLOWED=GDK_VERSION_4_2 hello.c -o hello `pkg-config --libs gtk4`
+</programlisting>
+</para>
+
+<para>
+The older deprecation mechanism of hiding deprecated interfaces
+entirely from the compiler by using the preprocessor symbol
+GTK_DISABLE_DEPRECATED is still used for deprecated macros,
+enumeration values, etc. To detect uses of these in your code,
+use the commandline option <literal>-DGTK_DISABLE_DEPRECATED</literal>.
+There are similar symbols GDK_DISABLE_DEPRECATED,
+GDK_PIXBUF_DISABLE_DEPRECATED and G_DISABLE_DEPRECATED for GDK, GdkPixbuf and
+GLib.
+</para>
+
+</refsect1>
+</refentry>
</refsect1>
</refentry>
-
-<!--
-Local variables:
-mode: xml
-sgml-parent-document: ("gtk-docs.sgml" "book" "part" "refentry")
-End:
--->
</glossdef>
</glossentry>
</glossary>
-
-<!--
-Local variables:
-mode: sgml
-sgml-parent-document: ("gtk-docs.sgml" "book" "glossary")
-End:
--->
<title>GTK Overview</title>
<xi:include href="overview.xml"/>
<xi:include href="xml/getting_started.xml"/>
- <xi:include href="resources.sgml" />
- <xi:include href="xml/question_index.sgml" />
+ <xi:include href="resources.xml" />
+ <xi:include href="xml/question_index.xml" />
<xi:include href="xml/drawing-model.xml" />
<xi:include href="xml/input-handling.xml" />
<xi:include href="xml/actions.xml" />
<chapter id="TextWidgetObjects">
<title>Multiline Text Editor</title>
- <xi:include href="xml/text_widget.sgml" />
+ <xi:include href="xml/text_widget.xml" />
<xi:include href="xml/gtktextiter.xml" />
<xi:include href="xml/gtktextmark.xml" />
<xi:include href="xml/gtktextbuffer.xml" />
<chapter id="TreeWidgetObjects">
<title>Tree, List and Icon Grid Widgets</title>
- <xi:include href="xml/tree_widget.sgml" />
+ <xi:include href="xml/tree_widget.xml" />
<xi:include href="xml/gtktreemodel.xml" />
<xi:include href="xml/gtktreeselection.xml" />
<xi:include href="xml/gtktreeviewcolumn.xml" />
<part id="platform-support">
<title>GTK Platform Support</title>
- <xi:include href="building.sgml" />
- <xi:include href="xml/compiling.sgml" />
- <xi:include href="running.sgml" />
- <xi:include href="x11.sgml" />
- <xi:include href="windows.sgml" />
- <xi:include href="osx.sgml" />
+ <xi:include href="building.xml" />
+ <xi:include href="xml/compiling.xml" />
+ <xi:include href="running.xml" />
+ <xi:include href="x11.xml" />
+ <xi:include href="windows.xml" />
+ <xi:include href="osx.xml" />
<xi:include href="broadway.xml" />
<xi:include href="wayland.xml" />
</part>
content_files = [
'actions.xml',
'broadway.xml',
- 'building.sgml',
- 'compiling.sgml',
+ 'building.xml',
+ 'compiling.xml',
'css-overview.xml',
'css-properties.xml',
'drawing-model.xml',
'input-handling.xml',
'migrating-2to4.xml',
'migrating-3to4.xml',
- 'osx.sgml',
- 'other_software.sgml',
+ 'osx.xml',
+ 'other_software.xml',
'overview.xml',
- 'question_index.sgml',
- 'resources.sgml',
- 'running.sgml',
- 'text_widget.sgml',
- 'tree_widget.sgml',
+ 'question_index.xml',
+ 'resources.xml',
+ 'running.xml',
+ 'text_widget.xml',
+ 'tree_widget.xml',
'visual_index.xml',
'wayland.xml',
- 'windows.sgml',
- 'x11.sgml',
+ 'windows.xml',
+ 'x11.xml',
]
expand_content_files = [
'actions.xml',
- 'compiling.sgml',
+ 'compiling.xml',
'drawing-model.xml',
'glossary.xml',
'input-handling.xml',
'migrating-2to4.xml',
'migrating-3to4.xml',
- 'question_index.sgml',
- 'text_widget.sgml',
- 'tree_widget.sgml',
+ 'question_index.xml',
+ 'text_widget.xml',
+ 'tree_widget.xml',
]
types_conf = configuration_data()
+++ /dev/null
-<?xml version="1.0"?>
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
- "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
-]>
-<refentry id="gtk-osx">
-<refmeta>
-<refentrytitle>Using GTK on Apple macOS</refentrytitle>
-<manvolnum>3</manvolnum>
-<refmiscinfo>GTK Library</refmiscinfo>
-</refmeta>
-
-<refnamediv>
-<refname>Using GTK on Apple macOS</refname>
-<refpurpose>
-MacOS-specific aspects of using GTK
-</refpurpose>
-</refnamediv>
-
-<refsect1>
-<title>Using GTK on Apple macOS</title>
-
-<para>
-The Apple macOS port of GTK is an implementation of GDK (and therefore GTK)
-on top of the Quartz API.
-</para>
-
-<para>
-Currently, the macOS port does not use any additional commandline options
-or environment variables.
-</para>
-
-<para>
-For up-to-date information about the current status of this port, see the
-<ulink url="https://wiki.gnome.org/Projects/GTK/OSX">project page</ulink>.
-</para>
-
-</refsect1>
-
-</refentry>
--- /dev/null
+<?xml version="1.0"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
+]>
+<refentry id="gtk-osx">
+<refmeta>
+<refentrytitle>Using GTK on Apple macOS</refentrytitle>
+<manvolnum>3</manvolnum>
+<refmiscinfo>GTK Library</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+<refname>Using GTK on Apple macOS</refname>
+<refpurpose>
+MacOS-specific aspects of using GTK
+</refpurpose>
+</refnamediv>
+
+<refsect1>
+<title>Using GTK on Apple macOS</title>
+
+<para>
+The Apple macOS port of GTK is an implementation of GDK (and therefore GTK)
+on top of the Quartz API.
+</para>
+
+<para>
+Currently, the macOS port does not use any additional commandline options
+or environment variables.
+</para>
+
+<para>
+For up-to-date information about the current status of this port, see the
+<ulink url="https://wiki.gnome.org/Projects/GTK/OSX">project page</ulink>.
+</para>
+
+</refsect1>
+
+</refentry>
+++ /dev/null
-<?xml version="1.0"?>
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
- "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
-]>
-<refentry id="gtk-other-software">
-<refmeta>
-<refentrytitle>Mixing GTK with other software</refentrytitle>
-<manvolnum>3</manvolnum>
-<refmiscinfo>Mixing GTK with other software</refmiscinfo>
-</refmeta>
-
-<refnamediv>
-<refname>Mixing GTK with other software</refname>
-<refpurpose>
-How to combine GTK with other code and event loops
-</refpurpose>
-</refnamediv>
-
-<refsect1>
-<title>Overview</title>
-
-<para>
-Often people want to use GTK in combination with another library or existing
-body of code that is not GTK-aware. The general problem people encounter
-is that the control flow of the other code does not return to GTK, so
-widgets do not repaint, mouse and keyboard events are ignored, and so forth.
-</para>
-
-<para>
-This section describes some approaches to solving this problem. The most
-suitable approach depends on the code that's involved, the platforms you're
-targetting, and your own familiarity with each approach.
-</para>
-
-</refsect1>
-
-<refsect1>
-<title>Periodically yield to GTK main loop</title>
-
-<para>
-This is the simplest method, but requires you to modify the non-GTK code.
-Say you have a function that does some kind of lengthy task:
-<informalexample>
-<programlisting>
- void
- do_lengthy_task (void)
- {
- int i;
- for (i = 0; i < BIG_NUMBER; ++i)
- {
- do_small_part_of_task ();
- }
- }
-</programlisting>
-</informalexample>
-You simply insert code into this function that processes pending main loop tasks, if any:
-<informalexample>
-<programlisting>
- void
- do_lengthy_task (void)
- {
- int i;
- for (i = 0; i < BIG_NUMBER; ++i)
- {
- do_small_part_of_task ();
-
- /* allow main loop to process pending events; NULL
- * means the default context.
- */
- while (g_main_context_pending (NULL))
- g_main_context_iteration (NULL, FALSE);
- }
- }
-</programlisting>
-</informalexample>
-</para>
-
-<para>
-The primary disadvantage of this approach is that you have to trade off UI
-responsiveness and the performance of the task. That is, if
-do_small_part_of_task() does very little of the task, you'll spend lots of CPU
-time on <link
-linkend="g-main-context-iteration">g_main_context_iteration()</link>. While if
-do_small_part_of_task() does a lot of work, the GUI will seem noticeably
-"chunky" to the user.
-</para>
-
-<para>
-Another disadvantage to this approach is that you can't have more than one
-lengthy task at the same time, unless you manually integrate them.
-</para>
-
-<para>
-The big advantage of this approach is that it's simple and straightforward, and
-works fine for simple applications such as tossing up a progress bar during the
-lengthy task.
-</para>
-
-</refsect1>
-
-<refsect1>
-<title>Run the other code as a slave of the GTK main loop</title>
-
-<para>
-As a slightly cleaner solution, you can ask the main loop to run a small part of your
-task whenever it isn't busy — that is, when it's <firstterm>idle</firstterm>.
-GLib provides a function <link linkend="g-idle-add">g_idle_add()</link> that's useful
-for this. An "idle handler" added with <link linkend="g-idle-add">g_idle_add()</link>
-will be run continuously as long as it returns <literal>TRUE</literal>. However,
-the main loop gives higher priority to GUI-related tasks, so will run those instead
-when appropriate.
-</para>
-
-<para>
-Here's a simple example:
-<informalexample>
-<programlisting>
- gboolean
- my_idle_handler (gpointer user_data)
- {
- do_small_part_of_task ();
-
- if (task_complete)
- return G_SOURCE_REMOVE; /* removes the idle handler */
- else
- return G_SOURCE_CONTINUE; /* runs the idle handler again */
- }
-
- g_idle_add (my_idle_handler, NULL);
-</programlisting>
-</informalexample>
-</para>
-
-<para>
-If your task involves reading data from the network, you should instead use
-<link linkend="g-input-add">g_input_add()</link>; this will allow the
-main loop to sleep until data is available on a file descriptor, then
-wake up to read that data.
-</para>
-
-<para>
-<link linkend="g-idle-add">g_idle_add()</link> returns a main loop source ID you can
-use to remove the idle handler with <link linkend="g-source-remove">g_source_remove()</link>.
-This is useful for cancelling a task, for example. Another approach is to keep a flag
-variable and have the idle handler itself return <literal>FALSE</literal> when appropriate.
-</para>
-
-</refsect1>
-
-<refsect1>
-<title>Use multiple processes</title>
-
-<para>
-If you can't break a task into small chunks — the
-"do_small_part_of_task()" function in the above examples — you'll have to
-separate your program into two parts, by spawning a child thread or process.
-A process does not share the same address space (variables and data) with its parent.
-A thread does share the same address space, so a change made to a variable in
-one thread will be visible to other threads as well.
-</para>
-
-<para>
-This manual can't go into full detail on processes, threads, and other UNIX
-programming topics. You may wish to get a book or two — two I'm familiar
-with are Beginning Linux Programming (WROX Press) and Advanced Programming in
-the UNIX Environment (by Richard Stevens.
-</para>
-
-<para>
-Those books also cover the central issue you'll need to address in order to have
-a multi-process application: how to communicate between the processes. The
-simplest solution is to use pipes; <link
-linkend="g-input-add">g_input_add()</link> in combination with <link
-linkend="g-spawn-async-with-pipes">g_spawn_async_with_pipes()</link> should make
-this reasonably convenient. There are other possibilities, of course, such as
-sockets, shared memory, and X Window System client message events, depending on
-your needs.
-</para>
-
-</refsect1>
-
-
-<refsect1>
-<title>Use multiple threads</title>
-
-<para>
-
-</para>
-
-</refsect1>
-
-<refsect1>
-<title>Integrate the GTK main loop with another main loop</title>
-
-<para>
-</para>
-
-</refsect1>
-
-
-<refsect1>
-<title>Things that won't work</title>
-
-<para>
-signals
-</para>
-
-</refsect1>
-
-
-</refentry>
--- /dev/null
+<?xml version="1.0"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
+]>
+<refentry id="gtk-other-software">
+<refmeta>
+<refentrytitle>Mixing GTK with other software</refentrytitle>
+<manvolnum>3</manvolnum>
+<refmiscinfo>Mixing GTK with other software</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+<refname>Mixing GTK with other software</refname>
+<refpurpose>
+How to combine GTK with other code and event loops
+</refpurpose>
+</refnamediv>
+
+<refsect1>
+<title>Overview</title>
+
+<para>
+Often people want to use GTK in combination with another library or existing
+body of code that is not GTK-aware. The general problem people encounter
+is that the control flow of the other code does not return to GTK, so
+widgets do not repaint, mouse and keyboard events are ignored, and so forth.
+</para>
+
+<para>
+This section describes some approaches to solving this problem. The most
+suitable approach depends on the code that's involved, the platforms you're
+targetting, and your own familiarity with each approach.
+</para>
+
+</refsect1>
+
+<refsect1>
+<title>Periodically yield to GTK main loop</title>
+
+<para>
+This is the simplest method, but requires you to modify the non-GTK code.
+Say you have a function that does some kind of lengthy task:
+<informalexample>
+<programlisting>
+ void
+ do_lengthy_task (void)
+ {
+ int i;
+ for (i = 0; i < BIG_NUMBER; ++i)
+ {
+ do_small_part_of_task ();
+ }
+ }
+</programlisting>
+</informalexample>
+You simply insert code into this function that processes pending main loop tasks, if any:
+<informalexample>
+<programlisting>
+ void
+ do_lengthy_task (void)
+ {
+ int i;
+ for (i = 0; i < BIG_NUMBER; ++i)
+ {
+ do_small_part_of_task ();
+
+ /* allow main loop to process pending events; NULL
+ * means the default context.
+ */
+ while (g_main_context_pending (NULL))
+ g_main_context_iteration (NULL, FALSE);
+ }
+ }
+</programlisting>
+</informalexample>
+</para>
+
+<para>
+The primary disadvantage of this approach is that you have to trade off UI
+responsiveness and the performance of the task. That is, if
+do_small_part_of_task() does very little of the task, you'll spend lots of CPU
+time on <link
+linkend="g-main-context-iteration">g_main_context_iteration()</link>. While if
+do_small_part_of_task() does a lot of work, the GUI will seem noticeably
+"chunky" to the user.
+</para>
+
+<para>
+Another disadvantage to this approach is that you can't have more than one
+lengthy task at the same time, unless you manually integrate them.
+</para>
+
+<para>
+The big advantage of this approach is that it's simple and straightforward, and
+works fine for simple applications such as tossing up a progress bar during the
+lengthy task.
+</para>
+
+</refsect1>
+
+<refsect1>
+<title>Run the other code as a slave of the GTK main loop</title>
+
+<para>
+As a slightly cleaner solution, you can ask the main loop to run a small part of your
+task whenever it isn't busy — that is, when it's <firstterm>idle</firstterm>.
+GLib provides a function <link linkend="g-idle-add">g_idle_add()</link> that's useful
+for this. An "idle handler" added with <link linkend="g-idle-add">g_idle_add()</link>
+will be run continuously as long as it returns <literal>TRUE</literal>. However,
+the main loop gives higher priority to GUI-related tasks, so will run those instead
+when appropriate.
+</para>
+
+<para>
+Here's a simple example:
+<informalexample>
+<programlisting>
+ gboolean
+ my_idle_handler (gpointer user_data)
+ {
+ do_small_part_of_task ();
+
+ if (task_complete)
+ return G_SOURCE_REMOVE; /* removes the idle handler */
+ else
+ return G_SOURCE_CONTINUE; /* runs the idle handler again */
+ }
+
+ g_idle_add (my_idle_handler, NULL);
+</programlisting>
+</informalexample>
+</para>
+
+<para>
+If your task involves reading data from the network, you should instead use
+<link linkend="g-input-add">g_input_add()</link>; this will allow the
+main loop to sleep until data is available on a file descriptor, then
+wake up to read that data.
+</para>
+
+<para>
+<link linkend="g-idle-add">g_idle_add()</link> returns a main loop source ID you can
+use to remove the idle handler with <link linkend="g-source-remove">g_source_remove()</link>.
+This is useful for cancelling a task, for example. Another approach is to keep a flag
+variable and have the idle handler itself return <literal>FALSE</literal> when appropriate.
+</para>
+
+</refsect1>
+
+<refsect1>
+<title>Use multiple processes</title>
+
+<para>
+If you can't break a task into small chunks — the
+"do_small_part_of_task()" function in the above examples — you'll have to
+separate your program into two parts, by spawning a child thread or process.
+A process does not share the same address space (variables and data) with its parent.
+A thread does share the same address space, so a change made to a variable in
+one thread will be visible to other threads as well.
+</para>
+
+<para>
+This manual can't go into full detail on processes, threads, and other UNIX
+programming topics. You may wish to get a book or two — two I'm familiar
+with are Beginning Linux Programming (WROX Press) and Advanced Programming in
+the UNIX Environment (by Richard Stevens.
+</para>
+
+<para>
+Those books also cover the central issue you'll need to address in order to have
+a multi-process application: how to communicate between the processes. The
+simplest solution is to use pipes; <link
+linkend="g-input-add">g_input_add()</link> in combination with <link
+linkend="g-spawn-async-with-pipes">g_spawn_async_with_pipes()</link> should make
+this reasonably convenient. There are other possibilities, of course, such as
+sockets, shared memory, and X Window System client message events, depending on
+your needs.
+</para>
+
+</refsect1>
+
+
+<refsect1>
+<title>Use multiple threads</title>
+
+<para>
+
+</para>
+
+</refsect1>
+
+<refsect1>
+<title>Integrate the GTK main loop with another main loop</title>
+
+<para>
+</para>
+
+</refsect1>
+
+
+<refsect1>
+<title>Things that won't work</title>
+
+<para>
+signals
+</para>
+
+</refsect1>
+
+
+</refentry>
+++ /dev/null
-<?xml version="1.0"?>
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
- "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
-]>
-<refentry id="gtk-question-index">
-<refmeta>
-<refentrytitle>Common Questions</refentrytitle>
-<manvolnum>3</manvolnum>
-<refmiscinfo>Common Questions</refmiscinfo>
-</refmeta>
-
-<refnamediv>
-<refname>Common Questions</refname>
-<refpurpose>
-Find answers to common questions in the GTK manual
-</refpurpose>
-</refnamediv>
-
-<refsect1>
-<title>Questions and Answers</title>
-
-<para>
-This is an "index" of the reference manual organized by common "How do
-I..." questions. If you aren't sure which documentation to read for
-the question you have, this list is a good place to start.
-</para>
-
-<qandaset>
-
-<qandadiv><title>General</title>
-
-<qandaentry>
-<question><para>
-How do I get started with GTK?
-</para></question>
-
-<answer><para>
-The GTK <ulink url="https://www.gtk.org">website</ulink> offers some
-<ulink url="https://www.gtk.org/documentation.php">tutorials</ulink> and other
-documentation (most of it about GTK 2.x, but mostly still applicable).
-More documentation ranging from whitepapers to online books can be found at
-the <ulink url="https://developer.gnome.org">GNOME developer's site</ulink>.
-After studying these materials you should be well prepared to come back to
-this reference manual for details.
-</para></answer>
-</qandaentry>
-
-<qandaentry>
-<question><para>
-Where can I get help with GTK, submit a bug report, or make a feature request?
-</para></question>
-
-<answer>
-
-<para>
-See the <link linkend="gtk-resources">documentation on this topic</link>.
-</para>
-
-</answer>
-
-</qandaentry>
-
-
-<qandaentry>
-<question><para>
-How do I port from one GTK version to another?
-</para></question>
-
-<answer>
-
-<para>
-See <xref linkend="migrating"/>.
-You may also find useful information in the documentation for
-specific widgets and functions.
-</para>
-
-<para>
-If you have a question not covered in the manual, feel free to
-ask on the mailing lists and please <ulink
-url="https://gitlab.gnome.org/GNOME/gtk/issues/new">file a bug report</ulink>
-against the documentation.
-</para>
-
-</answer>
-
-</qandaentry>
-
-
-<qandaentry>
-<question><para>
-How does memory management work in GTK? Should I free data returned from functions?
-</para></question>
-
-<answer>
-
-<para>
-See the documentation for #GObject and #GInitiallyUnowned. For #GObject note
-specifically g_object_ref() and g_object_unref(). #GInitiallyUnowned is a
-subclass of #GObject so the same points apply, except that it has a "floating"
-state (explained in its documentation).
-</para>
-
-<para>
-For strings returned from functions, they will be declared "const"
-if they should not be freed. Non-const strings should be
-freed with g_free(). Arrays follow the same rule. If you find an
-undocumented exception to the rules, please
-<ulink url="https://gitlab.gnome.org/GNOME/gtk/issues/new">file a bug report</ulink>.
-</para>
-
-</answer>
-</qandaentry>
-
-<qandaentry>
-<question>
-<para>
-Why does my program leak memory, if I destroy a widget immediately
-after creating it ?
-</para>
-</question>
-
-<answer>
-<para>
-If <structname>GtkFoo</structname> isn't a toplevel window, then
-<informalexample><programlisting>
- foo = gtk_foo_new (<!-- -->);
- gtk_widget_destroy (foo);
-</programlisting></informalexample>
-is a memory leak, because no one assumed the initial floating
-reference. If you are using a widget and you aren't immediately
-packing it into a container, then you probably want standard
-reference counting, not floating reference counting.
-</para>
-
-<para>
-To get this, you must acquire a reference to the widget and drop the
-floating reference (<quote>ref and sink</quote> in GTK parlance) after
-creating it:
-<informalexample><programlisting>
- foo = gtk_foo_new (<!-- -->);
- g_object_ref_sink (foo);
-</programlisting></informalexample>
-When you want to get rid of the widget, you must call gtk_widget_destroy()
-to break any external connections to the widget before dropping your
-reference:
-<informalexample><programlisting>
- gtk_widget_destroy (foo);
- g_object_unref (foo);
-</programlisting></informalexample>
-When you immediately add a widget to a container, it takes care of
-assuming the initial floating reference and you don't have to worry
-about reference counting at all ... just call gtk_widget_destroy()
-to get rid of the widget.
-</para>
-</answer>
-</qandaentry>
-
-<qandaentry>
-<question><para>
-How do I use GTK with threads?
-</para></question>
-
-<answer>
-
-<para>
-This is covered in the <link linkend="gdk-Threads">GDK threads
-documentation</link>. See also the <link linkend="glib-Threads">GThread</link>
-documentation for portable threading primitives.
-</para>
-
-</answer>
-
-</qandaentry>
-
-<qandaentry>
-<question><para>
-How do I internationalize a GTK program?
-</para></question>
-
-<answer>
-<para>
-Most people use <ulink url="https://www.gnu.org/software/gettext/">GNU
-gettext</ulink>, already required in order to install GLib. On a UNIX
-or Linux system with gettext installed, type <literal>info gettext</literal>
-to read the documentation.
-</para>
-<para>
-The short checklist on how to use gettext is: call <literal>bindtextdomain(<!-- -->)</literal> so
-gettext can find the files containing your translations, call textdomain()
-to set the default translation domain, call <literal>bind_textdomain_codeset(<!-- -->)</literal> to
-request that all translated strings are returned in UTF-8, then call
-gettext() to look up each string to be translated in the default domain.
-</para>
-<para>
-<filename>gi18n.h</filename> provides the following shorthand macros for
-convenience.
-Conventionally, people define macros as follows for convenience:
-<informalexample>
-<programlisting>
- #define _(x) gettext (x)
- #define N_(x) x
- #define C_(ctx,x) pgettext (ctx, x)
-</programlisting>
-</informalexample>
-You use N_() (N stands for no-op) to mark a string for translation in
-a location where a function call to gettext() is not allowed, such as
-in an array initializer.
-You eventually have to call gettext() on the string to actually fetch
-the translation. _() both marks the string for translation and actually
-translates it.
-The C_() macro (C stands for context) adds an additional context to
-the string that is marked for translation, which can help to disambiguate
-short strings that might need different translations in different
-parts of your program.
-</para>
-<para>
-Code using these macros ends up looking like this:
-<informalexample>
-<programlisting>
- #include <gi18n.h>
-
- static const char *global_variable = N_("Translate this string");
-
- static void
- make_widgets (void)
- {
- GtkWidget *label1;
- GtkWidget *label2;
-
- label1 = gtk_label_new (_("Another string to translate"));
- label2 = gtk_label_new (_(global_variable));
-...
-</programlisting>
-</informalexample>
-</para>
-<para>
-Libraries using gettext should use dgettext() instead of gettext(), which
-allows them to specify the translation domain each time they ask for a
-translation. Libraries should also avoid calling textdomain(), since
-they will be specifying the domain instead of using the default.
-</para>
-<para>
-With the convention that the macro <literal>GETTEXT_PACKAGE</literal> is
-defined to hold your libraries translation domain,
-<filename>gi18n-lib.h</filename> can be included to provide
-the following convenience:
-<informalexample>
-<programlisting>
- #define _(x) dgettext (GETTEXT_PACKAGE, x)
-</programlisting>
-</informalexample>
-</para>
-</answer>
-</qandaentry>
-
-<qandaentry>
-<question>
-<para>
-How do I use non-ASCII characters in GTK programs ?
-</para>
-</question>
-
-<answer>
-<para>
-GTK uses <ulink url="http://www.unicode.org">Unicode</ulink> (more exactly
-UTF-8) for all text. UTF-8 encodes each Unicode codepoint as a sequence of
-one to six bytes and has a number of nice properties which make it a good
-choice for working with Unicode text in C programs:
-<itemizedlist>
-<listitem><para>
-ASCII characters are encoded by their familiar ASCII codepoints.
-</para></listitem>
-<listitem><para>
-ASCII characters never appear as part of any other character.
-</para></listitem>
-<listitem><para>
-The zero byte doesn't occur as part of a character, so that UTF-8 strings
-can be manipulated with the usual C library functions for handling
-zero-terminated strings.
-</para></listitem>
-</itemizedlist>
-More information about Unicode and UTF-8 can be found in the
-<ulink url="https://www.cl.cam.ac.uk/~mgk25/unicode.html">UTF-8 and Unicode
-FAQ for Unix/Linux</ulink>.
-GLib provides functions for converting strings between UTF-8 and other
-encodings, see g_locale_to_utf8() and g_convert().
-</para>
-<para>
-Text coming from external sources (e.g. files or user input), has to be
-converted to UTF-8 before being handed over to GTK. The following example
-writes the content of a IS0-8859-1 encoded text file to
-<literal>stdout</literal>:
-<informalexample><programlisting>
-gchar *text, *utf8_text;
-gsize length;
-GError *error = NULL;
-
-if (g_file_get_contents (filename, &text, &length, NULL))
- {
- utf8_text = g_convert (text, length, "UTF-8", "ISO-8859-1",
- NULL, NULL, &error);
- if (error != NULL)
- {
- fprintf ("Couldn't convert file %s to UTF-8\n", filename);
- g_error_free (error);
- }
- else
- g_print (utf8_text);
- }
-else
- fprintf (stderr, "Unable to read file %s\n", filename);
-</programlisting></informalexample>
-</para>
-<para>
-For string literals in the source code, there are several alternatives for
-handling non-ASCII content:
-<variablelist>
-<varlistentry><term>direct UTF-8</term>
-<listitem><para>
-If your editor and compiler are capable of handling UTF-8 encoded sources,
-it is very convenient to simply use UTF-8 for string literals, since it
-allows you to edit the strings in "wysiwyg". Note that choosing this option
-may reduce the portability of your code.
-</para></listitem>
-</varlistentry>
-
-<varlistentry><term>escaped UTF-8</term>
-<listitem><para>
-Even if your toolchain can't handle UTF-8 directly, you can still encode
-string literals in UTF-8 by using octal or hexadecimal escapes like
-<literal>\212</literal> or <literal>\xa8</literal> to encode each byte.
-This is portable, but modifying the escaped strings is not very convenient.
-Be careful when mixing hexadecimal escapes with ordinary text;
-<literal>"\xa8abcd"</literal> is a string of length 1 !
-</para></listitem>
-</varlistentry>
-
-<varlistentry><term>runtime conversion</term>
-<listitem><para>
-If the string literals can be represented in an encoding which your
-toolchain can handle (e.g. IS0-8859-1), you can write your source files
-in that encoding and use g_convert() to convert the strings to UTF-8 at
-runtime. Note that this has some runtime overhead, so you may want to move
-the conversion out of inner loops.
-</para></listitem>
-</varlistentry>
-</variablelist>
-Here is an example showing the three approaches using the copyright sign
-© which has Unicode and ISO-8859-1 codepoint 169 and is represented
-in UTF-8 by the two bytes 194, 169, or <literal>"\302\251"</literal> as
-a string literal:
-<informalexample><programlisting>
-g_print ("direct UTF-8: ©");
-g_print ("escaped UTF-8: \302\251");
-text = g_convert ("runtime conversion: ©", -1, "ISO-8859-1", "UTF-8", NULL, NULL, NULL);
-g_print(text);
-g_free (text);
-</programlisting></informalexample>
-</para>
-<para>
-If you are using gettext() to localize your application, you need to
-call <literal>bind_textdomain_codeset(<!-- -->)</literal> to ensure that translated strings are
-returned in UTF-8 encoding.
-</para>
-</answer>
-</qandaentry>
-
-<qandaentry>
-<question><para>
-How do I use GTK with C++?
-</para></question>
-
-<answer>
-<para>
-There are two ways to approach this. The GTK header files use the subset
-of C that's also valid C++, so you can simply use the normal GTK API
-in a C++ program. Alternatively, you can use a "C++ binding"
-such as <ulink url="https://www.gtkmm.org/">gtkmm</ulink>
-which provides a native C++ API.
-</para>
-<para>
-When using GTK directly, keep in mind that only functions can be
-connected to signals, not methods. So you will need to use global
-functions or "static" class functions for signal connections.
-</para>
-<para>
-Another common issue when using GTK directly is that
-C++ will not implicitly convert an integer to an enumeration.
-This comes up when using bitfields; in C you can write the following
-code:
-<informalexample>
-<programlisting>
- gdk_surface_set_events (gdk_surface,
- GDK_BUTTON_PRESS_MASK | GDK_BUTTON_RELEASE_MASK);
-</programlisting>
-</informalexample>
-while in C++ you must write:
-<informalexample>
-<programlisting>
- gdk_surface_set_events (gdk_surface,
- (GdkEventMask) GDK_BUTTON_PRESS_MASK | GDK_BUTTON_RELEASE_MASK);
-</programlisting>
-</informalexample>
-There are very few functions that require this cast, however.
-</para>
-</answer>
-
-</qandaentry>
-
-<qandaentry>
-<question><para>
-How do I use GTK with other non-C languages?
-</para></question>
-
-<answer>
-<para>
-See the <ulink url="https://www.gtk.org/language-bindings.php">list of language
-bindings</ulink> on <ulink
-url="https://www.gtk.org">https://www.gtk.org</ulink>.
-</para>
-
-</answer>
-
-</qandaentry>
-
-<qandaentry>
-<question><para>
-How do I load an image or animation from a file?
-</para></question>
-
-<answer>
-
-<para>
-To load an image file straight into a display widget, use
-gtk_image_new_from_file() <footnote><para> If the file load fails,
-gtk_image_new_from_file() will display no image graphic — to detect
-a failed load yourself, use gdk_pixbuf_new_from_file() directly, then
-gtk_image_new_from_pixbuf().</para></footnote>.
-To load an image for another purpose, use gdk_pixbuf_new_from_file(). To
-load an animation, use gdk_pixbuf_animation_new_from_file().
-gdk_pixbuf_animation_new_from_file() can also load non-animated images, so
-use it in combination with gdk_pixbuf_animation_is_static_image() to load a
-file of unknown type.
-</para>
-<para>
-To load an image or animation file asynchronously (without blocking), use
-#GdkPixbufLoader.
-</para>
-</answer>
-
-</qandaentry>
-
-<qandaentry>
-<question><para>
-How do I draw text ?
-</para></question>
-
-<answer>
-<para>
-To draw a piece of text, use a Pango layout and pango_cairo_show_layout().
-<informalexample>
-<programlisting>
- layout = gtk_widget_create_pango_layout (widget, text);
- fontdesc = pango_font_description_from_string ("Luxi Mono 12");
- pango_layout_set_font_description (layout, fontdesc);
- pango_cairo_show_layout (cr, layout);
- pango_font_description_free (fontdesc);
- g_object_unref (layout);
-</programlisting>
-</informalexample>
-</para>
-
-<para>
-See also the
-<ulink url="https://developer.gnome.org/pango/stable/pango-Cairo-Rendering.html">Cairo Rendering</ulink>
-section of <ulink url="https://developer.gnome.org/pango/stable/">Pango manual</ulink>.
-</para>
-</answer>
-
-</qandaentry>
-
-<qandaentry>
-<question>
-<para>
-How do I measure the size of a piece of text ?
-</para>
-</question>
-
-<answer>
-<para>
-To obtain the size of a piece of text, use a Pango layout and
-pango_layout_get_pixel_size(), using code like the following:
-<informalexample>
-<programlisting>
- layout = gtk_widget_create_pango_layout (widget, text);
- fontdesc = pango_font_description_from_string ("Luxi Mono 12");
- pango_layout_set_font_description (layout, fontdesc);
- pango_layout_get_pixel_size (layout, &width, &height);
- pango_font_description_free (fontdesc);
- g_object_unref (layout);
-</programlisting>
-</informalexample>
-</para>
-
-<para>
-See also the
-<ulink url="https://developer.gnome.org/pango/stable/pango-Layout-Objects.html">Layout Objects</ulink>
-section of <ulink url="https://developer.gnome.org/pango/stable/">Pango manual</ulink>.
-</para>
-</answer>
-</qandaentry>
-
-<qandaentry>
-<question>
-<para>
-Why are types not registered if I use their <literal>GTK_TYPE_BLAH</literal>
-macro ?
-</para>
-</question>
-
-<answer>
-<para>
-The <literal>GTK_TYPE_BLAH</literal> macros are defined as calls to
-<literal>gtk_blah_get_type(<!-- -->)</literal>, and the <literal>_get_type(<!-- -->)</literal>
-functions are declared as %G_GNUC_CONST which allows the compiler to optimize
-the call away if it appears that the value is not being used.
-</para>
-
-<para>
-GLib provides the g_type_ensure() function to work around this problem.
-<informalexample><programlisting>
- g_type_ensure (GTK_TYPE_BLAH);
-</programlisting></informalexample>
-</para>
-</answer>
-</qandaentry>
-
-<qandaentry>
-<question>
-<para>
-How do I create a transparent toplevel window ?
-</para>
-</question>
-
-<answer>
-<para>
-Any toplevel window can be transparent.
-It is just a matter of setting a transparent background
-in the CSS style for it.
-</para>
-</answer>
-</qandaentry>
-
-</qandadiv>
-
-<qandadiv><title>Which widget should I use...</title>
-
-<qandaentry>
-<question><para>
-...for lists and trees?
-</para></question>
-
-<answer>
-<para>
-This question has different answers, depending on the size of the dataset
-and the required formatting flexibility.
-</para>
-<para>
-If you want to display a large amount of data in a uniform way, your
-best option is a #GtkTreeView widget. See <link linkend="TreeWidget">tree
-widget overview</link>. A list is just a tree with no branches, so the treeview
-widget is used for lists as well.
-</para>
-<para>
-If you want to display a small amount of items, but need flexible formatting
-and widgetry inside the list, then you probably want to use a #GtkListBox,
-which uses regular widgets for display.
-</para>
-</answer>
-</qandaentry>
-
-<qandaentry>
-<question><para>
-...for multi-line text display or editing?
-</para></question>
-
-<answer>
-<para>
-See <link linkend="TextWidget">text widget overview</link> — you
-should use the #GtkTextView widget.
-</para>
-<para>
-If you only have a small amount of text, #GtkLabel may also be appropriate
-of course. It can be made selectable with gtk_label_set_selectable(). For a
-single-line text entry, see #GtkEntry.
-</para>
-</answer>
-</qandaentry>
-
-
-<qandaentry>
-<question><para>
-...to display an image or animation?
-</para></question>
-
-<answer>
-<para>
-GTK has two widgets that are dedicated to displaying images. #GtkImage, for
-small, fixed-size icons and #GtkPicture for content images.
-</para>
-<para>
-Both can display images in just about any format GTK understands.
-You can also use #GtkDrawingArea if you need to do something more complex,
-such as draw text or graphics over the top of the image.
-</para>
-</answer>
-</qandaentry>
-
-<qandaentry>
-<question><para>
-...for presenting a set of mutually-exclusive choices, where Windows
-would use a combo box?
-</para></question>
-
-<answer>
-<para>
-With GTK, a #GtkComboBox is the recommended widget to use for this use case.
-This widget looks like either a combo box or the current option menu, depending
-on the current theme. If you need an editable text entry, use the
-#GtkComboBox:has-entry property.
-</para>
-</answer>
-</qandaentry>
-
-</qandadiv>
-
-<qandadiv><title>GtkWidget</title>
-
-<qandaentry>
-<question><para>
-How do I change the color of a widget?
-</para></question>
-
-<answer><para>
-The background color of a widget is determined by the CSS style that applies
-to it. To change that, you can set style classes on the widget, and provide
-custom CSS to change the appearance. Such CSS can be loaded with
-gtk_css_provider_load_from_file() and its variants. See gtk_style_context_add_provider().
-</para></answer>
-</qandaentry>
-
-<qandaentry>
-<question><para>
-How do I change the font of a widget?
-</para></question>
-
-<answer><para>
-If you want to make the text of a label larger, you can use
-gtk_label_set_markup():
-<informalexample><programlisting>
-gtk_label_set_markup (label, "<big>big text</big>");
-</programlisting></informalexample>
-This is preferred for many apps because it's a relative size to the
-user's chosen font size. See g_markup_escape_text() if you are
-constructing such strings on the fly.
-</para>
-<para>
-You can also change the font of a widget by putting
-<programlisting>
- .my-widget-class {
- font: Sans 30;
- }
-</programlisting>
-in a CSS file, loading it with gtk_css_provider_load_from_file(), and
-adding the provider with gtk_style_context_add_provider_for_display().
-To associate this style information with your widget, set a style class
-on its #GtkStyleContext using gtk_style_context_add_class().
-The advantage of this approach is that users can then override the font
-you have chosen. See the #GtkStyleContext documentation for more discussion.
-</para>
-</answer>
-</qandaentry>
-
-<qandaentry>
-<question><para>
-How do I disable/ghost/desensitize a widget?
-</para></question>
-
-<answer><para>
-In GTK a disabled widget is termed "insensitive."
-See gtk_widget_set_sensitive().
-</para></answer>
-</qandaentry>
-
-</qandadiv>
-
-
-<qandadiv><title>GtkTextView</title>
-
-<qandaentry>
-<question><para>
-How do I get the contents of the entire text widget as a string?
-</para></question>
-
-<answer><para>
-See gtk_text_buffer_get_bounds() and gtk_text_buffer_get_text()
-or gtk_text_iter_get_text().
-</para>
-<para>
-<informalexample><programlisting>
- GtkTextIter start, end;
- GtkTextBuffer *buffer;
- char *text;
-
- buffer = gtk_text_view_get_buffer (GTK_TEXT_VIEW (text_view));
- gtk_text_buffer_get_bounds (buffer, &start, &end);
- text = gtk_text_iter_get_text (&start, &end);
- /* use text */
- g_free (text);
-</programlisting></informalexample>
-</para></answer>
-</qandaentry>
-
-<qandaentry>
-<question><para>
-How do I make a text widget display its complete contents in a specific font?
-</para></question>
-
-<answer><para>
-If you use gtk_text_buffer_insert_with_tags() with appropriate tags to
-select the font, the inserted text will have the desired appearance, but
-text typed in by the user before or after the tagged block will appear in
-the default style.
-</para>
-<para>
-To ensure that all text has the desired appearance, use
-gtk_widget_override_font() to change the default font for the widget.
-</para></answer>
-</qandaentry>
-
-<qandaentry>
-<question>
-<para>
-How do I make a text view scroll to the end of the buffer automatically ?
-</para>
-</question>
-
-<answer>
-<para>
-A good way to keep a text buffer scrolled to the end is to place a
-<link linkend="GtkTextMark">mark</link> at the end of the buffer, and
-give it right gravity. The gravity has the effect that text inserted
-at the mark gets inserted <emphasis>before</emphasis>, keeping the mark
-at the end.
-</para>
-
-<para>
-To ensure that the end of the buffer remains visible, use
-gtk_text_view_scroll_to_mark() to scroll to the mark after
-inserting new text.
-</para>
-
-<para>
-The gtk-demo application contains an example of this technique.
-</para>
-</answer>
-</qandaentry>
-</qandadiv>
-
-
-
-<qandadiv><title>#GtkTreeView</title>
-
-<qandaentry>
-<question><para>
-How do I associate some data with a row in the tree?
-</para></question>
-
-<answer>
-<para>
-Remember that the #GtkTreeModel columns don't necessarily have to be
-displayed. So you can put non-user-visible data in your model just
-like any other data, and retrieve it with gtk_tree_model_get().
-See the <link linkend="TreeWidget">tree widget overview</link>.
-</para>
-</answer>
-</qandaentry>
-
-<qandaentry>
-<question><para>
-How do I put an image and some text in the same column?
-</para></question>
-
-<answer>
-<para>
-You can pack more than one #GtkCellRenderer into a single #GtkTreeViewColumn
-using gtk_tree_view_column_pack_start() or gtk_tree_view_column_pack_end().
-So pack both a #GtkCellRendererPixbuf and a #GtkCellRendererText into the
-column.
-</para>
-</answer>
-</qandaentry>
-
-<qandaentry>
-<question><para>
-I can set data easily on my #GtkTreeStore/#GtkListStore models using
-gtk_list_store_set() and gtk_tree_store_set(), but can't read it back?
-</para></question>
-
-<answer>
-<para>
-Both the #GtkTreeStore and the #GtkListStore implement the #GtkTreeModel
-interface. Consequentially, you can use any function this interface
-implements. The easiest way to read a set of data back is to use
-gtk_tree_model_get().
-</para>
-</answer>
-</qandaentry>
-
-<qandaentry>
-<question><para>
-How do I change the way that numbers are formatted by #GtkTreeView?
-</para></question>
-<answer><para>
-Use gtk_tree_view_insert_column_with_data_func()
-or gtk_tree_view_column_set_cell_data_func() and do the conversion
-from number to string yourself (with, say, g_strdup_printf()).
-</para>
-
-<para>
-The following example demonstrates this:
-<informalexample><programlisting>
-enum
-{
- DOUBLE_COLUMN,
- N_COLUMNS
-};
-
-GtkListStore *mycolumns;
-GtkTreeView *treeview;
-
-void
-my_cell_double_to_text (GtkTreeViewColumn *tree_column,
- GtkCellRenderer *cell,
- GtkTreeModel *tree_model,
- GtkTreeIter *iter,
- gpointer data)
-{
- GtkCellRendererText *cell_text = (GtkCellRendererText *)cell;
- gdouble d;
- gchar *text;
-
- /* Get the double value from the model. */
- gtk_tree_model_get (tree_model, iter, (gint)data, &d, -1);
- /* Now we can format the value ourselves. */
- text = g_strdup_printf ("%.2f", d);
- g_object_set (cell, "text", text, NULL);
- g_free (text);
-}
-
-void
-set_up_new_columns (GtkTreeView *myview)
-{
- GtkCellRendererText *renderer;
- GtkTreeViewColumn *column;
- GtkListStore *mycolumns;
-
- /* Create the data model and associate it with the given TreeView */
- mycolumns = gtk_list_store_new (N_COLUMNS, G_TYPE_DOUBLE);
- gtk_tree_view_set_model (myview, GTK_TREE_MODEL (mycolumns));
-
- /* Create a GtkCellRendererText */
- renderer = gtk_cell_renderer_text_new (<!-- -->);
-
- /* Create a new column that has a title ("Example column"),
- * uses the above created renderer that will render the double
- * value into text from the associated model's rows.
- */
- column = gtk_tree_view_column_new (<!-- -->);
- gtk_tree_view_column_set_title (column, "Example column");
- renderer = gtk_cell_renderer_text_new (<!-- -->);
- gtk_tree_view_column_pack_start (column, renderer, TRUE);
-
- /* Append the new column after the GtkTreeView's previous columns. */
- gtk_tree_view_append_column (GTK_TREE_VIEW (myview), column);
- /* Since we created the column by hand, we can set it up for our
- * needs, e.g. set its minimum and maximum width, etc.
- */
- /* Set up a custom function that will be called when the column content
- * is rendered. We use the func_data pointer as an index into our
- * model. This is convenient when using multi column lists.
- */
- gtk_tree_view_column_set_cell_data_func (column, renderer,
- my_cell_double_to_text,
- (gpointer)DOUBLE_COLUMN, NULL);
-}
-</programlisting></informalexample>
-</para></answer>
-</qandaentry>
-
-<qandaentry>
-<question><para>
-How do I hide the expander arrows in my tree view ?
-</para></question>
-
-<answer><para>
-Set the expander-column property of the tree view to a hidden column.
-See gtk_tree_view_set_expander_column() and gtk_tree_view_column_set_visible().
-</para></answer>
-</qandaentry>
-
-</qandadiv>
-
-<qandadiv><title>Using cairo with GTK</title>
-
-<qandaentry>
-<question><para>
-How do I use cairo to draw in GTK applications ?
-</para></question>
-
-<answer><para>
-Use gtk_snapshot_append_cairo() in your #GtkWidget::snapshot signal handler
-to optain a cairo context and draw with that.
-</para>
-</answer>
-</qandaentry>
-
-<qandaentry>
-<question><para>
-Can I improve the performance of my application by using another backend
-of cairo (such as GL) ?
-</para></question>
-
-<answer><para>
-No. Most drawing in GTK is not done via cairo anymore (but instead
-by the GL or Vulkan renderers of GSK).
-</para>
-<para>
-If you use cairo for drawing your own widgets, gtk_snapshot_append_cairo()
-will choose the most appropriate surface type for you.
-</para>
-<para>
-If you are interested in using GL for your own drawing, see #GtkGLArea.
-</para></answer>
-</qandaentry>
-
-<qandaentry>
-<question><para>
-Can I use cairo to draw on a #GdkPixbuf ?
-</para></question>
-
-<answer><para>
-No. The cairo image surface does not support the pixel format used by GdkPixbuf.
-</para>
-<para>
-If you need to get cairo drawing into a format that can be displayed efficiently
-by GTK, you may want to use an image surface and gdk_memory_texture_new().
-</para></answer>
-</qandaentry>
-
-</qandadiv>
-
-</qandaset>
-
-</refsect1>
-
-</refentry>
--- /dev/null
+<?xml version="1.0"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
+]>
+<refentry id="gtk-question-index">
+<refmeta>
+<refentrytitle>Common Questions</refentrytitle>
+<manvolnum>3</manvolnum>
+<refmiscinfo>Common Questions</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+<refname>Common Questions</refname>
+<refpurpose>
+Find answers to common questions in the GTK manual
+</refpurpose>
+</refnamediv>
+
+<refsect1>
+<title>Questions and Answers</title>
+
+<para>
+This is an "index" of the reference manual organized by common "How do
+I..." questions. If you aren't sure which documentation to read for
+the question you have, this list is a good place to start.
+</para>
+
+<qandaset>
+
+<qandadiv><title>General</title>
+
+<qandaentry>
+<question><para>
+How do I get started with GTK?
+</para></question>
+
+<answer><para>
+The GTK <ulink url="https://www.gtk.org">website</ulink> offers some
+<ulink url="https://www.gtk.org/documentation.php">tutorials</ulink> and other
+documentation (most of it about GTK 2.x, but mostly still applicable).
+More documentation ranging from whitepapers to online books can be found at
+the <ulink url="https://developer.gnome.org">GNOME developer's site</ulink>.
+After studying these materials you should be well prepared to come back to
+this reference manual for details.
+</para></answer>
+</qandaentry>
+
+<qandaentry>
+<question><para>
+Where can I get help with GTK, submit a bug report, or make a feature request?
+</para></question>
+
+<answer>
+
+<para>
+See the <link linkend="gtk-resources">documentation on this topic</link>.
+</para>
+
+</answer>
+
+</qandaentry>
+
+
+<qandaentry>
+<question><para>
+How do I port from one GTK version to another?
+</para></question>
+
+<answer>
+
+<para>
+See <xref linkend="migrating"/>.
+You may also find useful information in the documentation for
+specific widgets and functions.
+</para>
+
+<para>
+If you have a question not covered in the manual, feel free to
+ask on the mailing lists and please <ulink
+url="https://gitlab.gnome.org/GNOME/gtk/issues/new">file a bug report</ulink>
+against the documentation.
+</para>
+
+</answer>
+
+</qandaentry>
+
+
+<qandaentry>
+<question><para>
+How does memory management work in GTK? Should I free data returned from functions?
+</para></question>
+
+<answer>
+
+<para>
+See the documentation for #GObject and #GInitiallyUnowned. For #GObject note
+specifically g_object_ref() and g_object_unref(). #GInitiallyUnowned is a
+subclass of #GObject so the same points apply, except that it has a "floating"
+state (explained in its documentation).
+</para>
+
+<para>
+For strings returned from functions, they will be declared "const"
+if they should not be freed. Non-const strings should be
+freed with g_free(). Arrays follow the same rule. If you find an
+undocumented exception to the rules, please
+<ulink url="https://gitlab.gnome.org/GNOME/gtk/issues/new">file a bug report</ulink>.
+</para>
+
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question>
+<para>
+Why does my program leak memory, if I destroy a widget immediately
+after creating it ?
+</para>
+</question>
+
+<answer>
+<para>
+If <structname>GtkFoo</structname> isn't a toplevel window, then
+<informalexample><programlisting>
+ foo = gtk_foo_new (<!-- -->);
+ gtk_widget_destroy (foo);
+</programlisting></informalexample>
+is a memory leak, because no one assumed the initial floating
+reference. If you are using a widget and you aren't immediately
+packing it into a container, then you probably want standard
+reference counting, not floating reference counting.
+</para>
+
+<para>
+To get this, you must acquire a reference to the widget and drop the
+floating reference (<quote>ref and sink</quote> in GTK parlance) after
+creating it:
+<informalexample><programlisting>
+ foo = gtk_foo_new (<!-- -->);
+ g_object_ref_sink (foo);
+</programlisting></informalexample>
+When you want to get rid of the widget, you must call gtk_widget_destroy()
+to break any external connections to the widget before dropping your
+reference:
+<informalexample><programlisting>
+ gtk_widget_destroy (foo);
+ g_object_unref (foo);
+</programlisting></informalexample>
+When you immediately add a widget to a container, it takes care of
+assuming the initial floating reference and you don't have to worry
+about reference counting at all ... just call gtk_widget_destroy()
+to get rid of the widget.
+</para>
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question><para>
+How do I use GTK with threads?
+</para></question>
+
+<answer>
+
+<para>
+This is covered in the <link linkend="gdk-Threads">GDK threads
+documentation</link>. See also the <link linkend="glib-Threads">GThread</link>
+documentation for portable threading primitives.
+</para>
+
+</answer>
+
+</qandaentry>
+
+<qandaentry>
+<question><para>
+How do I internationalize a GTK program?
+</para></question>
+
+<answer>
+<para>
+Most people use <ulink url="https://www.gnu.org/software/gettext/">GNU
+gettext</ulink>, already required in order to install GLib. On a UNIX
+or Linux system with gettext installed, type <literal>info gettext</literal>
+to read the documentation.
+</para>
+<para>
+The short checklist on how to use gettext is: call <literal>bindtextdomain(<!-- -->)</literal> so
+gettext can find the files containing your translations, call textdomain()
+to set the default translation domain, call <literal>bind_textdomain_codeset(<!-- -->)</literal> to
+request that all translated strings are returned in UTF-8, then call
+gettext() to look up each string to be translated in the default domain.
+</para>
+<para>
+<filename>gi18n.h</filename> provides the following shorthand macros for
+convenience.
+Conventionally, people define macros as follows for convenience:
+<informalexample>
+<programlisting>
+ #define _(x) gettext (x)
+ #define N_(x) x
+ #define C_(ctx,x) pgettext (ctx, x)
+</programlisting>
+</informalexample>
+You use N_() (N stands for no-op) to mark a string for translation in
+a location where a function call to gettext() is not allowed, such as
+in an array initializer.
+You eventually have to call gettext() on the string to actually fetch
+the translation. _() both marks the string for translation and actually
+translates it.
+The C_() macro (C stands for context) adds an additional context to
+the string that is marked for translation, which can help to disambiguate
+short strings that might need different translations in different
+parts of your program.
+</para>
+<para>
+Code using these macros ends up looking like this:
+<informalexample>
+<programlisting>
+ #include <gi18n.h>
+
+ static const char *global_variable = N_("Translate this string");
+
+ static void
+ make_widgets (void)
+ {
+ GtkWidget *label1;
+ GtkWidget *label2;
+
+ label1 = gtk_label_new (_("Another string to translate"));
+ label2 = gtk_label_new (_(global_variable));
+...
+</programlisting>
+</informalexample>
+</para>
+<para>
+Libraries using gettext should use dgettext() instead of gettext(), which
+allows them to specify the translation domain each time they ask for a
+translation. Libraries should also avoid calling textdomain(), since
+they will be specifying the domain instead of using the default.
+</para>
+<para>
+With the convention that the macro <literal>GETTEXT_PACKAGE</literal> is
+defined to hold your libraries translation domain,
+<filename>gi18n-lib.h</filename> can be included to provide
+the following convenience:
+<informalexample>
+<programlisting>
+ #define _(x) dgettext (GETTEXT_PACKAGE, x)
+</programlisting>
+</informalexample>
+</para>
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question>
+<para>
+How do I use non-ASCII characters in GTK programs ?
+</para>
+</question>
+
+<answer>
+<para>
+GTK uses <ulink url="http://www.unicode.org">Unicode</ulink> (more exactly
+UTF-8) for all text. UTF-8 encodes each Unicode codepoint as a sequence of
+one to six bytes and has a number of nice properties which make it a good
+choice for working with Unicode text in C programs:
+<itemizedlist>
+<listitem><para>
+ASCII characters are encoded by their familiar ASCII codepoints.
+</para></listitem>
+<listitem><para>
+ASCII characters never appear as part of any other character.
+</para></listitem>
+<listitem><para>
+The zero byte doesn't occur as part of a character, so that UTF-8 strings
+can be manipulated with the usual C library functions for handling
+zero-terminated strings.
+</para></listitem>
+</itemizedlist>
+More information about Unicode and UTF-8 can be found in the
+<ulink url="https://www.cl.cam.ac.uk/~mgk25/unicode.html">UTF-8 and Unicode
+FAQ for Unix/Linux</ulink>.
+GLib provides functions for converting strings between UTF-8 and other
+encodings, see g_locale_to_utf8() and g_convert().
+</para>
+<para>
+Text coming from external sources (e.g. files or user input), has to be
+converted to UTF-8 before being handed over to GTK. The following example
+writes the content of a IS0-8859-1 encoded text file to
+<literal>stdout</literal>:
+<informalexample><programlisting>
+gchar *text, *utf8_text;
+gsize length;
+GError *error = NULL;
+
+if (g_file_get_contents (filename, &text, &length, NULL))
+ {
+ utf8_text = g_convert (text, length, "UTF-8", "ISO-8859-1",
+ NULL, NULL, &error);
+ if (error != NULL)
+ {
+ fprintf ("Couldn't convert file %s to UTF-8\n", filename);
+ g_error_free (error);
+ }
+ else
+ g_print (utf8_text);
+ }
+else
+ fprintf (stderr, "Unable to read file %s\n", filename);
+</programlisting></informalexample>
+</para>
+<para>
+For string literals in the source code, there are several alternatives for
+handling non-ASCII content:
+<variablelist>
+<varlistentry><term>direct UTF-8</term>
+<listitem><para>
+If your editor and compiler are capable of handling UTF-8 encoded sources,
+it is very convenient to simply use UTF-8 for string literals, since it
+allows you to edit the strings in "wysiwyg". Note that choosing this option
+may reduce the portability of your code.
+</para></listitem>
+</varlistentry>
+
+<varlistentry><term>escaped UTF-8</term>
+<listitem><para>
+Even if your toolchain can't handle UTF-8 directly, you can still encode
+string literals in UTF-8 by using octal or hexadecimal escapes like
+<literal>\212</literal> or <literal>\xa8</literal> to encode each byte.
+This is portable, but modifying the escaped strings is not very convenient.
+Be careful when mixing hexadecimal escapes with ordinary text;
+<literal>"\xa8abcd"</literal> is a string of length 1 !
+</para></listitem>
+</varlistentry>
+
+<varlistentry><term>runtime conversion</term>
+<listitem><para>
+If the string literals can be represented in an encoding which your
+toolchain can handle (e.g. IS0-8859-1), you can write your source files
+in that encoding and use g_convert() to convert the strings to UTF-8 at
+runtime. Note that this has some runtime overhead, so you may want to move
+the conversion out of inner loops.
+</para></listitem>
+</varlistentry>
+</variablelist>
+Here is an example showing the three approaches using the copyright sign
+© which has Unicode and ISO-8859-1 codepoint 169 and is represented
+in UTF-8 by the two bytes 194, 169, or <literal>"\302\251"</literal> as
+a string literal:
+<informalexample><programlisting>
+g_print ("direct UTF-8: ©");
+g_print ("escaped UTF-8: \302\251");
+text = g_convert ("runtime conversion: ©", -1, "ISO-8859-1", "UTF-8", NULL, NULL, NULL);
+g_print(text);
+g_free (text);
+</programlisting></informalexample>
+</para>
+<para>
+If you are using gettext() to localize your application, you need to
+call <literal>bind_textdomain_codeset(<!-- -->)</literal> to ensure that translated strings are
+returned in UTF-8 encoding.
+</para>
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question><para>
+How do I use GTK with C++?
+</para></question>
+
+<answer>
+<para>
+There are two ways to approach this. The GTK header files use the subset
+of C that's also valid C++, so you can simply use the normal GTK API
+in a C++ program. Alternatively, you can use a "C++ binding"
+such as <ulink url="https://www.gtkmm.org/">gtkmm</ulink>
+which provides a native C++ API.
+</para>
+<para>
+When using GTK directly, keep in mind that only functions can be
+connected to signals, not methods. So you will need to use global
+functions or "static" class functions for signal connections.
+</para>
+<para>
+Another common issue when using GTK directly is that
+C++ will not implicitly convert an integer to an enumeration.
+This comes up when using bitfields; in C you can write the following
+code:
+<informalexample>
+<programlisting>
+ gdk_surface_set_events (gdk_surface,
+ GDK_BUTTON_PRESS_MASK | GDK_BUTTON_RELEASE_MASK);
+</programlisting>
+</informalexample>
+while in C++ you must write:
+<informalexample>
+<programlisting>
+ gdk_surface_set_events (gdk_surface,
+ (GdkEventMask) GDK_BUTTON_PRESS_MASK | GDK_BUTTON_RELEASE_MASK);
+</programlisting>
+</informalexample>
+There are very few functions that require this cast, however.
+</para>
+</answer>
+
+</qandaentry>
+
+<qandaentry>
+<question><para>
+How do I use GTK with other non-C languages?
+</para></question>
+
+<answer>
+<para>
+See the <ulink url="https://www.gtk.org/language-bindings.php">list of language
+bindings</ulink> on <ulink
+url="https://www.gtk.org">https://www.gtk.org</ulink>.
+</para>
+
+</answer>
+
+</qandaentry>
+
+<qandaentry>
+<question><para>
+How do I load an image or animation from a file?
+</para></question>
+
+<answer>
+
+<para>
+To load an image file straight into a display widget, use
+gtk_image_new_from_file() <footnote><para> If the file load fails,
+gtk_image_new_from_file() will display no image graphic — to detect
+a failed load yourself, use gdk_pixbuf_new_from_file() directly, then
+gtk_image_new_from_pixbuf().</para></footnote>.
+To load an image for another purpose, use gdk_pixbuf_new_from_file(). To
+load an animation, use gdk_pixbuf_animation_new_from_file().
+gdk_pixbuf_animation_new_from_file() can also load non-animated images, so
+use it in combination with gdk_pixbuf_animation_is_static_image() to load a
+file of unknown type.
+</para>
+<para>
+To load an image or animation file asynchronously (without blocking), use
+#GdkPixbufLoader.
+</para>
+</answer>
+
+</qandaentry>
+
+<qandaentry>
+<question><para>
+How do I draw text ?
+</para></question>
+
+<answer>
+<para>
+To draw a piece of text, use a Pango layout and pango_cairo_show_layout().
+<informalexample>
+<programlisting>
+ layout = gtk_widget_create_pango_layout (widget, text);
+ fontdesc = pango_font_description_from_string ("Luxi Mono 12");
+ pango_layout_set_font_description (layout, fontdesc);
+ pango_cairo_show_layout (cr, layout);
+ pango_font_description_free (fontdesc);
+ g_object_unref (layout);
+</programlisting>
+</informalexample>
+</para>
+
+<para>
+See also the
+<ulink url="https://developer.gnome.org/pango/stable/pango-Cairo-Rendering.html">Cairo Rendering</ulink>
+section of <ulink url="https://developer.gnome.org/pango/stable/">Pango manual</ulink>.
+</para>
+</answer>
+
+</qandaentry>
+
+<qandaentry>
+<question>
+<para>
+How do I measure the size of a piece of text ?
+</para>
+</question>
+
+<answer>
+<para>
+To obtain the size of a piece of text, use a Pango layout and
+pango_layout_get_pixel_size(), using code like the following:
+<informalexample>
+<programlisting>
+ layout = gtk_widget_create_pango_layout (widget, text);
+ fontdesc = pango_font_description_from_string ("Luxi Mono 12");
+ pango_layout_set_font_description (layout, fontdesc);
+ pango_layout_get_pixel_size (layout, &width, &height);
+ pango_font_description_free (fontdesc);
+ g_object_unref (layout);
+</programlisting>
+</informalexample>
+</para>
+
+<para>
+See also the
+<ulink url="https://developer.gnome.org/pango/stable/pango-Layout-Objects.html">Layout Objects</ulink>
+section of <ulink url="https://developer.gnome.org/pango/stable/">Pango manual</ulink>.
+</para>
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question>
+<para>
+Why are types not registered if I use their <literal>GTK_TYPE_BLAH</literal>
+macro ?
+</para>
+</question>
+
+<answer>
+<para>
+The <literal>GTK_TYPE_BLAH</literal> macros are defined as calls to
+<literal>gtk_blah_get_type(<!-- -->)</literal>, and the <literal>_get_type(<!-- -->)</literal>
+functions are declared as %G_GNUC_CONST which allows the compiler to optimize
+the call away if it appears that the value is not being used.
+</para>
+
+<para>
+GLib provides the g_type_ensure() function to work around this problem.
+<informalexample><programlisting>
+ g_type_ensure (GTK_TYPE_BLAH);
+</programlisting></informalexample>
+</para>
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question>
+<para>
+How do I create a transparent toplevel window ?
+</para>
+</question>
+
+<answer>
+<para>
+Any toplevel window can be transparent.
+It is just a matter of setting a transparent background
+in the CSS style for it.
+</para>
+</answer>
+</qandaentry>
+
+</qandadiv>
+
+<qandadiv><title>Which widget should I use...</title>
+
+<qandaentry>
+<question><para>
+...for lists and trees?
+</para></question>
+
+<answer>
+<para>
+This question has different answers, depending on the size of the dataset
+and the required formatting flexibility.
+</para>
+<para>
+If you want to display a large amount of data in a uniform way, your
+best option is a #GtkTreeView widget. See <link linkend="TreeWidget">tree
+widget overview</link>. A list is just a tree with no branches, so the treeview
+widget is used for lists as well.
+</para>
+<para>
+If you want to display a small amount of items, but need flexible formatting
+and widgetry inside the list, then you probably want to use a #GtkListBox,
+which uses regular widgets for display.
+</para>
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question><para>
+...for multi-line text display or editing?
+</para></question>
+
+<answer>
+<para>
+See <link linkend="TextWidget">text widget overview</link> — you
+should use the #GtkTextView widget.
+</para>
+<para>
+If you only have a small amount of text, #GtkLabel may also be appropriate
+of course. It can be made selectable with gtk_label_set_selectable(). For a
+single-line text entry, see #GtkEntry.
+</para>
+</answer>
+</qandaentry>
+
+
+<qandaentry>
+<question><para>
+...to display an image or animation?
+</para></question>
+
+<answer>
+<para>
+GTK has two widgets that are dedicated to displaying images. #GtkImage, for
+small, fixed-size icons and #GtkPicture for content images.
+</para>
+<para>
+Both can display images in just about any format GTK understands.
+You can also use #GtkDrawingArea if you need to do something more complex,
+such as draw text or graphics over the top of the image.
+</para>
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question><para>
+...for presenting a set of mutually-exclusive choices, where Windows
+would use a combo box?
+</para></question>
+
+<answer>
+<para>
+With GTK, a #GtkComboBox is the recommended widget to use for this use case.
+This widget looks like either a combo box or the current option menu, depending
+on the current theme. If you need an editable text entry, use the
+#GtkComboBox:has-entry property.
+</para>
+</answer>
+</qandaentry>
+
+</qandadiv>
+
+<qandadiv><title>GtkWidget</title>
+
+<qandaentry>
+<question><para>
+How do I change the color of a widget?
+</para></question>
+
+<answer><para>
+The background color of a widget is determined by the CSS style that applies
+to it. To change that, you can set style classes on the widget, and provide
+custom CSS to change the appearance. Such CSS can be loaded with
+gtk_css_provider_load_from_file() and its variants. See gtk_style_context_add_provider().
+</para></answer>
+</qandaentry>
+
+<qandaentry>
+<question><para>
+How do I change the font of a widget?
+</para></question>
+
+<answer><para>
+If you want to make the text of a label larger, you can use
+gtk_label_set_markup():
+<informalexample><programlisting>
+gtk_label_set_markup (label, "<big>big text</big>");
+</programlisting></informalexample>
+This is preferred for many apps because it's a relative size to the
+user's chosen font size. See g_markup_escape_text() if you are
+constructing such strings on the fly.
+</para>
+<para>
+You can also change the font of a widget by putting
+<programlisting>
+ .my-widget-class {
+ font: Sans 30;
+ }
+</programlisting>
+in a CSS file, loading it with gtk_css_provider_load_from_file(), and
+adding the provider with gtk_style_context_add_provider_for_display().
+To associate this style information with your widget, set a style class
+on its #GtkStyleContext using gtk_style_context_add_class().
+The advantage of this approach is that users can then override the font
+you have chosen. See the #GtkStyleContext documentation for more discussion.
+</para>
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question><para>
+How do I disable/ghost/desensitize a widget?
+</para></question>
+
+<answer><para>
+In GTK a disabled widget is termed "insensitive."
+See gtk_widget_set_sensitive().
+</para></answer>
+</qandaentry>
+
+</qandadiv>
+
+
+<qandadiv><title>GtkTextView</title>
+
+<qandaentry>
+<question><para>
+How do I get the contents of the entire text widget as a string?
+</para></question>
+
+<answer><para>
+See gtk_text_buffer_get_bounds() and gtk_text_buffer_get_text()
+or gtk_text_iter_get_text().
+</para>
+<para>
+<informalexample><programlisting>
+ GtkTextIter start, end;
+ GtkTextBuffer *buffer;
+ char *text;
+
+ buffer = gtk_text_view_get_buffer (GTK_TEXT_VIEW (text_view));
+ gtk_text_buffer_get_bounds (buffer, &start, &end);
+ text = gtk_text_iter_get_text (&start, &end);
+ /* use text */
+ g_free (text);
+</programlisting></informalexample>
+</para></answer>
+</qandaentry>
+
+<qandaentry>
+<question><para>
+How do I make a text widget display its complete contents in a specific font?
+</para></question>
+
+<answer><para>
+If you use gtk_text_buffer_insert_with_tags() with appropriate tags to
+select the font, the inserted text will have the desired appearance, but
+text typed in by the user before or after the tagged block will appear in
+the default style.
+</para>
+<para>
+To ensure that all text has the desired appearance, use
+gtk_widget_override_font() to change the default font for the widget.
+</para></answer>
+</qandaentry>
+
+<qandaentry>
+<question>
+<para>
+How do I make a text view scroll to the end of the buffer automatically ?
+</para>
+</question>
+
+<answer>
+<para>
+A good way to keep a text buffer scrolled to the end is to place a
+<link linkend="GtkTextMark">mark</link> at the end of the buffer, and
+give it right gravity. The gravity has the effect that text inserted
+at the mark gets inserted <emphasis>before</emphasis>, keeping the mark
+at the end.
+</para>
+
+<para>
+To ensure that the end of the buffer remains visible, use
+gtk_text_view_scroll_to_mark() to scroll to the mark after
+inserting new text.
+</para>
+
+<para>
+The gtk-demo application contains an example of this technique.
+</para>
+</answer>
+</qandaentry>
+</qandadiv>
+
+
+
+<qandadiv><title>#GtkTreeView</title>
+
+<qandaentry>
+<question><para>
+How do I associate some data with a row in the tree?
+</para></question>
+
+<answer>
+<para>
+Remember that the #GtkTreeModel columns don't necessarily have to be
+displayed. So you can put non-user-visible data in your model just
+like any other data, and retrieve it with gtk_tree_model_get().
+See the <link linkend="TreeWidget">tree widget overview</link>.
+</para>
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question><para>
+How do I put an image and some text in the same column?
+</para></question>
+
+<answer>
+<para>
+You can pack more than one #GtkCellRenderer into a single #GtkTreeViewColumn
+using gtk_tree_view_column_pack_start() or gtk_tree_view_column_pack_end().
+So pack both a #GtkCellRendererPixbuf and a #GtkCellRendererText into the
+column.
+</para>
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question><para>
+I can set data easily on my #GtkTreeStore/#GtkListStore models using
+gtk_list_store_set() and gtk_tree_store_set(), but can't read it back?
+</para></question>
+
+<answer>
+<para>
+Both the #GtkTreeStore and the #GtkListStore implement the #GtkTreeModel
+interface. Consequentially, you can use any function this interface
+implements. The easiest way to read a set of data back is to use
+gtk_tree_model_get().
+</para>
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question><para>
+How do I change the way that numbers are formatted by #GtkTreeView?
+</para></question>
+<answer><para>
+Use gtk_tree_view_insert_column_with_data_func()
+or gtk_tree_view_column_set_cell_data_func() and do the conversion
+from number to string yourself (with, say, g_strdup_printf()).
+</para>
+
+<para>
+The following example demonstrates this:
+<informalexample><programlisting>
+enum
+{
+ DOUBLE_COLUMN,
+ N_COLUMNS
+};
+
+GtkListStore *mycolumns;
+GtkTreeView *treeview;
+
+void
+my_cell_double_to_text (GtkTreeViewColumn *tree_column,
+ GtkCellRenderer *cell,
+ GtkTreeModel *tree_model,
+ GtkTreeIter *iter,
+ gpointer data)
+{
+ GtkCellRendererText *cell_text = (GtkCellRendererText *)cell;
+ gdouble d;
+ gchar *text;
+
+ /* Get the double value from the model. */
+ gtk_tree_model_get (tree_model, iter, (gint)data, &d, -1);
+ /* Now we can format the value ourselves. */
+ text = g_strdup_printf ("%.2f", d);
+ g_object_set (cell, "text", text, NULL);
+ g_free (text);
+}
+
+void
+set_up_new_columns (GtkTreeView *myview)
+{
+ GtkCellRendererText *renderer;
+ GtkTreeViewColumn *column;
+ GtkListStore *mycolumns;
+
+ /* Create the data model and associate it with the given TreeView */
+ mycolumns = gtk_list_store_new (N_COLUMNS, G_TYPE_DOUBLE);
+ gtk_tree_view_set_model (myview, GTK_TREE_MODEL (mycolumns));
+
+ /* Create a GtkCellRendererText */
+ renderer = gtk_cell_renderer_text_new (<!-- -->);
+
+ /* Create a new column that has a title ("Example column"),
+ * uses the above created renderer that will render the double
+ * value into text from the associated model's rows.
+ */
+ column = gtk_tree_view_column_new (<!-- -->);
+ gtk_tree_view_column_set_title (column, "Example column");
+ renderer = gtk_cell_renderer_text_new (<!-- -->);
+ gtk_tree_view_column_pack_start (column, renderer, TRUE);
+
+ /* Append the new column after the GtkTreeView's previous columns. */
+ gtk_tree_view_append_column (GTK_TREE_VIEW (myview), column);
+ /* Since we created the column by hand, we can set it up for our
+ * needs, e.g. set its minimum and maximum width, etc.
+ */
+ /* Set up a custom function that will be called when the column content
+ * is rendered. We use the func_data pointer as an index into our
+ * model. This is convenient when using multi column lists.
+ */
+ gtk_tree_view_column_set_cell_data_func (column, renderer,
+ my_cell_double_to_text,
+ (gpointer)DOUBLE_COLUMN, NULL);
+}
+</programlisting></informalexample>
+</para></answer>
+</qandaentry>
+
+<qandaentry>
+<question><para>
+How do I hide the expander arrows in my tree view ?
+</para></question>
+
+<answer><para>
+Set the expander-column property of the tree view to a hidden column.
+See gtk_tree_view_set_expander_column() and gtk_tree_view_column_set_visible().
+</para></answer>
+</qandaentry>
+
+</qandadiv>
+
+<qandadiv><title>Using cairo with GTK</title>
+
+<qandaentry>
+<question><para>
+How do I use cairo to draw in GTK applications ?
+</para></question>
+
+<answer><para>
+Use gtk_snapshot_append_cairo() in your #GtkWidget::snapshot signal handler
+to optain a cairo context and draw with that.
+</para>
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question><para>
+Can I improve the performance of my application by using another backend
+of cairo (such as GL) ?
+</para></question>
+
+<answer><para>
+No. Most drawing in GTK is not done via cairo anymore (but instead
+by the GL or Vulkan renderers of GSK).
+</para>
+<para>
+If you use cairo for drawing your own widgets, gtk_snapshot_append_cairo()
+will choose the most appropriate surface type for you.
+</para>
+<para>
+If you are interested in using GL for your own drawing, see #GtkGLArea.
+</para></answer>
+</qandaentry>
+
+<qandaentry>
+<question><para>
+Can I use cairo to draw on a #GdkPixbuf ?
+</para></question>
+
+<answer><para>
+No. The cairo image surface does not support the pixel format used by GdkPixbuf.
+</para>
+<para>
+If you need to get cairo drawing into a format that can be displayed efficiently
+by GTK, you may want to use an image surface and gdk_memory_texture_new().
+</para></answer>
+</qandaentry>
+
+</qandadiv>
+
+</qandaset>
+
+</refsect1>
+
+</refentry>
+++ /dev/null
-<?xml version="1.0"?>
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
- "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
-]>
-<refentry id="gtk-resources">
-<refmeta>
-<refentrytitle>Mailing lists and bug reports</refentrytitle>
-<manvolnum>3</manvolnum>
-<refmiscinfo>Mailing lists and bug reports</refmiscinfo>
-</refmeta>
-
-<refnamediv>
-<refname>Mailing lists and bug reports</refname>
-<refpurpose>
-Getting help with GTK
-</refpurpose>
-</refnamediv>
-
-<refsect1>
-<title>Opening a bug or feature request</title>
-
-<para>
-If you encounter a bug, misfeature, or missing feature in GTK, please
-file a bug report on our
-<ulink url="https://gitlab.gnome.org/GNOME/gtk/issues/new">GitLab project</ulink>.
-You should also file issues if the documentation is out of date with the
-existing API, or unclear.
-</para>
-
-<para>
-Don't hesitate to file a bug report, even if you think we may know
-about it already, or aren't sure of the details. Just give us as much
-information as you have, and if it's already fixed or has already been
-discussed, we'll add a note to that effect in the report.
-</para>
-
-<para>
-The bug tracker should definitely be used for feature requests, it's
-not only for bugs. We track all GTK development in GitLab, to ensure
-that nothing gets lost.
-</para>
-
-</refsect1>
-
-<refsect1>
-<title>Working on GTK</title>
-
-<para>
-If you develop a bugfix or enhancement for GTK, please open a merge
-request in GitLab as well. You should not attach patches to an issue,
-or describe the fix as a comment. Merge requests allow us to build
-GTK with your code applied, and run the test suite, on multiple platforms
-and architectures, and verify that nothing breaks. They also allow us to
-do proper code reviews, so we can iterate over the changes.
-</para>
-
-<para>
-You should follow the <ulink url="https://gitlab.gnome.org/GNOME/gtk/blob/master/CONTRIBUTING.md">contribution guide</ulink>
-for GTK, available on GitLab.
-</para>
-
-<para>
-If you want to discuss your approach before or after working on it,
-send and email to <ulink url="mailto:gtk-devel-list@gnome.org">gtk-devel-list@gnome.org</ulink>.
-You should not send a patch to the mailing list, as it will inevitably
-get lost, or forgotten. Always open a merge request.
-</para>
-
-</refsect1>
-
-<refsect1>
-<title>Mailing lists</title>
-
-<para>
-There are several mailing lists dedicated to GTK and related
-libraries. Discussion of GLib, Pango, and ATK in addition to GTK
-proper is welcome on these lists. You can subscribe or view the
-archives of these lists on
-<ulink url="https://mail.gnome.org">http://mail.gnome.org</ulink>.
-If you aren't subscribed to the list, any message you post to
-the list will be held for manual moderation, which might take
-some days to happen.
-</para>
-
-<para>
-<variablelist>
-
-<varlistentry>
-<term><ulink url="mailto:gtk-list@gnome.org">gtk-list@gnome.org</ulink></term>
-<listitem><para>
-gtk-list covers general GTK topics; questions about using GTK in programs,
-GTK from a user standpoint, announcements of GTK-related projects
-such as themes or GTK modules would all be on-topic. The bulk of the
-traffic consists of GTK programming questions.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><ulink url="mailto:gtk-app-devel-list@gnome.org">gtk-app-devel-list@gnome.org</ulink></term>
-<listitem><para>
-gtk-app-devel-list covers writing applications in GTK. It's narrower
-in scope than gtk-list, but the two lists overlap quite a
-bit. gtk-app-devel-list is a good place to ask questions about GTK
-programming. </para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><ulink url="mailto:gtk-devel-list@gnome.org">gtk-devel-list@gnome.org</ulink></term>
-<listitem><para>
-gtk-devel-list is for discussion of work on GTK itself, it is
-<emphasis>not</emphasis> for
-asking questions about how to use GTK in applications. gtk-devel-list
-is appropriate for discussion of patches, bugs, proposed features,
-and so on.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><ulink url="mailto:gtk-i18n-list@gnome.org">gtk-i18n-list@gnome.org</ulink></term>
-<listitem><para>
-gtk-i18n-list is for discussion of internationalization in GTK;
-Pango is the main focus of the list. Questions about the details of
-using Pango, and discussion of proposed Pango patches or features, are
-all on topic.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><ulink url="mailto:gtk-doc-list@gnome.org">gtk-doc-list@gnome.org</ulink></term>
-<listitem><para>
-gtk-doc-list is for discussion of the <application>gtk-doc</application>
-documentation system (used to document GTK), and for work on the GTK
-documentation.
-</para></listitem>
-</varlistentry>
-
-</variablelist>
-</para>
-
-</refsect1>
-
-
-</refentry>
--- /dev/null
+<?xml version="1.0"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
+]>
+<refentry id="gtk-resources">
+<refmeta>
+<refentrytitle>Mailing lists and bug reports</refentrytitle>
+<manvolnum>3</manvolnum>
+<refmiscinfo>Mailing lists and bug reports</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+<refname>Mailing lists and bug reports</refname>
+<refpurpose>
+Getting help with GTK
+</refpurpose>
+</refnamediv>
+
+<refsect1>
+<title>Opening a bug or feature request</title>
+
+<para>
+If you encounter a bug, misfeature, or missing feature in GTK, please
+file a bug report on our
+<ulink url="https://gitlab.gnome.org/GNOME/gtk/issues/new">GitLab project</ulink>.
+You should also file issues if the documentation is out of date with the
+existing API, or unclear.
+</para>
+
+<para>
+Don't hesitate to file a bug report, even if you think we may know
+about it already, or aren't sure of the details. Just give us as much
+information as you have, and if it's already fixed or has already been
+discussed, we'll add a note to that effect in the report.
+</para>
+
+<para>
+The bug tracker should definitely be used for feature requests, it's
+not only for bugs. We track all GTK development in GitLab, to ensure
+that nothing gets lost.
+</para>
+
+</refsect1>
+
+<refsect1>
+<title>Working on GTK</title>
+
+<para>
+If you develop a bugfix or enhancement for GTK, please open a merge
+request in GitLab as well. You should not attach patches to an issue,
+or describe the fix as a comment. Merge requests allow us to build
+GTK with your code applied, and run the test suite, on multiple platforms
+and architectures, and verify that nothing breaks. They also allow us to
+do proper code reviews, so we can iterate over the changes.
+</para>
+
+<para>
+You should follow the <ulink url="https://gitlab.gnome.org/GNOME/gtk/blob/master/CONTRIBUTING.md">contribution guide</ulink>
+for GTK, available on GitLab.
+</para>
+
+<para>
+If you want to discuss your approach before or after working on it,
+send and email to <ulink url="mailto:gtk-devel-list@gnome.org">gtk-devel-list@gnome.org</ulink>.
+You should not send a patch to the mailing list, as it will inevitably
+get lost, or forgotten. Always open a merge request.
+</para>
+
+</refsect1>
+
+<refsect1>
+<title>Mailing lists</title>
+
+<para>
+There are several mailing lists dedicated to GTK and related
+libraries. Discussion of GLib, Pango, and ATK in addition to GTK
+proper is welcome on these lists. You can subscribe or view the
+archives of these lists on
+<ulink url="https://mail.gnome.org">http://mail.gnome.org</ulink>.
+If you aren't subscribed to the list, any message you post to
+the list will be held for manual moderation, which might take
+some days to happen.
+</para>
+
+<para>
+<variablelist>
+
+<varlistentry>
+<term><ulink url="mailto:gtk-list@gnome.org">gtk-list@gnome.org</ulink></term>
+<listitem><para>
+gtk-list covers general GTK topics; questions about using GTK in programs,
+GTK from a user standpoint, announcements of GTK-related projects
+such as themes or GTK modules would all be on-topic. The bulk of the
+traffic consists of GTK programming questions.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><ulink url="mailto:gtk-app-devel-list@gnome.org">gtk-app-devel-list@gnome.org</ulink></term>
+<listitem><para>
+gtk-app-devel-list covers writing applications in GTK. It's narrower
+in scope than gtk-list, but the two lists overlap quite a
+bit. gtk-app-devel-list is a good place to ask questions about GTK
+programming. </para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><ulink url="mailto:gtk-devel-list@gnome.org">gtk-devel-list@gnome.org</ulink></term>
+<listitem><para>
+gtk-devel-list is for discussion of work on GTK itself, it is
+<emphasis>not</emphasis> for
+asking questions about how to use GTK in applications. gtk-devel-list
+is appropriate for discussion of patches, bugs, proposed features,
+and so on.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><ulink url="mailto:gtk-i18n-list@gnome.org">gtk-i18n-list@gnome.org</ulink></term>
+<listitem><para>
+gtk-i18n-list is for discussion of internationalization in GTK;
+Pango is the main focus of the list. Questions about the details of
+using Pango, and discussion of proposed Pango patches or features, are
+all on topic.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><ulink url="mailto:gtk-doc-list@gnome.org">gtk-doc-list@gnome.org</ulink></term>
+<listitem><para>
+gtk-doc-list is for discussion of the <application>gtk-doc</application>
+documentation system (used to document GTK), and for work on the GTK
+documentation.
+</para></listitem>
+</varlistentry>
+
+</variablelist>
+</para>
+
+</refsect1>
+
+
+</refentry>
+++ /dev/null
-<?xml version="1.0"?>
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
- "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
-]>
-<refentry id="gtk-running">
-<refmeta>
-<refentrytitle>Running GTK Applications</refentrytitle>
-<manvolnum>3</manvolnum>
-<refmiscinfo>GTK Library</refmiscinfo>
-</refmeta>
-
-<refnamediv>
-<refname>Running GTK Applications</refname>
-<refpurpose>
-How to run and debug your GTK application
-</refpurpose>
-</refnamediv>
-
-<refsect1>
-<title>Running and debugging GTK Applications</title>
-
-<refsect2>
-<title>Environment variables</title>
-
-<para>
-GTK inspects a number of environment variables in addition to standard
-variables like <envar>LANG</envar>, <envar>PATH</envar>, <envar>HOME</envar>
-or <envar>DISPLAY</envar>; mostly to determine paths to look for certain
-files. The <link linkend="x11-envar">X11</link>,
-<link linkend="win32-envar">Windows</link> and
-<link linkend="broadway-envar">Broadway</link> GDK backends use some
-additional environment variables.
-</para>
-
-<formalpara id="GTK-Debug-Options">
- <title><envar>GTK_DEBUG</envar></title>
-
- <para>
- Unless GTK has been configured with <option>--enable-debug=no</option>,
- this variable can be set to a list of debug options, which cause GTK
- to print out different types of debugging information.
- <variablelist>
- <varlistentry>
- <term>actions</term>
- <listitem><para>Actions and menu models</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>builder</term>
- <listitem><para>GtkBuilder support</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>geometry</term>
- <listitem><para>Size allocation</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>icontheme</term>
- <listitem><para>Icon themes</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>keybindings</term>
- <listitem><para>Keybindings</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>modules</term>
- <listitem><para>Loading of modules</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>printing</term>
- <listitem><para>Printing support</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>size-request</term>
- <listitem><para>Size requests</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>text</term>
- <listitem><para>Text widget internals</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>tree</term>
- <listitem><para>Tree widget internals</para></listitem>
- </varlistentry>
- </variablelist>
- A number of keys are influencing behavior instead of just logging:
- <variablelist>
- <varlistentry>
- <term>interactive</term>
- <listitem><para>Open the <link linkend="interactive-debugging">interactive debugger</link></para></listitem>
- </varlistentry>
- <varlistentry>
- <term>no-css-cache</term>
- <listitem><para>Bypass caching for CSS style properties</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>touchscreen</term>
- <listitem><para>Pretend the pointer is a touchscreen device</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>baselines</term>
- <listitem><para>Show baselines</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>updates</term>
- <listitem><para>Visual feedback about window updates</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>resize</term>
- <listitem><para>Highlight resizing widgets</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>layout</term>
- <listitem><para>Show layout borders</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>snapshot</term>
- <listitem><para>Include debug render nodes in the generated snapshots</para></listitem>
- </varlistentry>
- </variablelist>
- The special value <literal>all</literal> can be used to turn on all
- debug options. The special value <literal>help</literal> can be used
- to obtain a list of all supported debug options.
- </para>
-</formalpara>
-
-<formalpara id="gtk-path">
- <title><envar>GTK_PATH</envar></title>
-
- <para>
- Specifies a list of directories to search when GTK is looking for
- dynamically loaded objects such as input method
- modules and print backends. If the path to
- the dynamically loaded object is given as an absolute path name,
- then GTK loads it directly.
- Otherwise, GTK goes in turn through the directories in <envar>GTK_PATH</envar>,
- followed by the directory <filename>.gtk-4.0</filename> in the user's
- home directory, followed by the system default directory,
- which is <filename><replaceable>libdir</replaceable>/gtk-4.0/modules</filename>.
- (If <envar>GTK_EXE_PREFIX</envar> is defined, <replaceable>libdir</replaceable> is
- <filename>$GTK_EXE_PREFIX/lib</filename>. Otherwise it is the libdir
- specified when GTK was configured, usually
- <filename>/usr/lib</filename>, or
- <filename>/usr/local/lib</filename>.)
- For each directory in this list, GTK actually looks in a
- subdirectory
- <filename><replaceable>directory</replaceable>/<replaceable>version</replaceable>/<replaceable>host</replaceable>/<replaceable>type</replaceable></filename>
- Where <replaceable>version</replaceable> is derived from the
- version of GTK (use <literal>pkg-config
- --variable=gtk_binary_version gtk4</literal> to determine this from a
- script), <replaceable>host</replaceable> is the architecture on
- which GTK was built. (use <literal>pkg-config
- --variable=gtk_host gtk4</literal> to determine this from a
- script), and <replaceable>type</replaceable> is a directory
- specific to the type of modules; currently it can be
- <literal>modules</literal>, <literal>engines</literal>,
- <literal>immodules</literal>, <literal>filesystems</literal> or
- <literal>printbackends</literal>, corresponding to the types of
- modules mentioned above. Either <replaceable>version</replaceable>,
- <replaceable>host</replaceable>, or both may be omitted. GTK looks
- first in the most specific directory, then in directories with
- fewer components.
- The components of GTK_PATH are separated by the ':' character on
- Linux and Unix, and the ';' character on Windows.
- </para>
- <warning>
- Note that this environment variable is read by GTK 2.x and GTK 3.x too,
- which makes it unsuitable for setting it system-wide (or session-wide),
- since doing so will cause applications using different GTK versions
- to see incompatible modules.
- </warning>
-</formalpara>
-
-<formalpara>
- <title><envar>GTK_IM_MODULE</envar></title>
-
- <para>
- Specifies an IM module to use in preference to the one determined
- from the locale. If this isn't set and you are running on the system
- that enables <literal>XSETTINGS</literal> and has a value in
- <literal>Gtk/IMModule</literal>, that will be used for the default
- IM module.
- This also can be a colon-separated list of input-methods, which
- GTK will try in turn until it finds one available on the system.
- </para>
-</formalpara>
-
-<formalpara>
- <title><envar>GTK_EXE_PREFIX</envar></title>
-
- <para>
- If set, GTK uses <filename>$GTK_EXE_PREFIX/lib</filename> instead of
- the libdir configured when GTK was compiled.
- </para>
-</formalpara>
-
-<formalpara>
- <title><envar>GTK_DATA_PREFIX</envar></title>
-
- <para>
- If set, makes GTK use <filename>$GTK_DATA_PREFIX</filename>
- instead of the prefix configured when GTK was compiled.
- </para>
-</formalpara>
-
-<formalpara>
- <title><envar>GTK_THEME</envar></title>
-
- <para>
- If set, makes GTK use the named theme instead of the theme
- that is specified by the gtk-theme-name setting. This is intended
- mainly for easy debugging of theme issues.
- </para>
- <para>
- It is also possible to specify a theme variant to load, by appending
- the variant name with a colon, like this: `GTK_THEME=Adwaita:dark`.
- </para>
-</formalpara>
-
-<para>
-The following environment variables are used by GdkPixbuf, GDK or
-Pango, not by GTK itself, but we list them here for completeness
-nevertheless.
-</para>
-
-<formalpara>
- <title><envar>GDK_PIXBUF_MODULE_FILE</envar></title>
-
- <para>
- Specifies the file listing the GdkPixbuf loader modules to load.
- This environment variable overrides the default value
- <filename><replaceable>libdir</replaceable>/gtk-4.0/4.0.0/loaders.cache</filename>
- (<replaceable>libdir</replaceable> is the sysconfdir specified when
- GTK was configured, usually <filename>/usr/local/lib</filename>.)
- </para>
- <para>
- The <filename>loaders.cache</filename> file is generated by the
- <command>gdk-pixbuf-query-loaders</command> utility.
- </para>
- </formalpara>
-
-<formalpara id="GDK-Debug-Options">
- <title><envar>GDK_DEBUG</envar></title>
-
- <para>
- If GTK has been configured with <option>--enable-debug=yes</option>,
- this variable can be set to a list of debug options, which cause GDK
- to print out different types of debugging information.
- <variablelist>
- <varlistentry>
- <term>cursor</term>
- <listitem><para>Information about cursor objects (only win32)</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>eventloop</term>
- <listitem><para>Information about event loop operation (mostly Quartz)</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>misc</term>
- <listitem><para>Miscellaneous information</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>frames</term>
- <listitem><para>Information about the frame clock</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>settings</term>
- <listitem><para>Information about xsettings</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>selection</term>
- <listitem><para>Information about selections</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>clipboard</term>
- <listitem><para>Information about clipboards</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>dnd</term>
- <listitem><para>Information about drag-and-drop</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>opengl</term>
- <listitem><para>Information about OpenGL</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>vulkan</term>
- <listitem><para>Information about Vulkan</para></listitem>
- </varlistentry>
- </variablelist>
- A number of options affect behavior instead of logging:
- <variablelist>
- <varlistentry>
- <term>nograbs</term>
- <listitem><para>Turn off all pointer and keyboard grabs</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>gl-disable</term>
- <listitem><para>Disable OpenGL support</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>gl-software</term>
- <listitem><para>Force OpenGL software rendering</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>gl-texture-rect</term>
- <listitem><para>Use the OpenGL texture rectangle extension, if available</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>gl-legacy</term>
- <listitem><para>Use a legacy OpenGL context</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>gl-gles</term>
- <listitem><para>Use a GLES OpenGL context</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>vulkan-disable</term>
- <listitem><para>Disable Vulkan support</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>vulkan-validate</term>
- <listitem><para>Load the Vulkan validation layer, if available</para></listitem>
- </varlistentry>
- </variablelist>
- The special value <literal>all</literal> can be used to turn on all
- debug options. The special value <literal>help</literal> can be used
- to obtain a list of all supported debug options.
- </para>
-</formalpara>
-
-<formalpara id="GSK-Debug-Options">
- <title><envar>GSK_DEBUG</envar></title>
-
- <para>
- If GTK has been configured with <option>--enable-debug=yes</option>,
- this variable can be set to a list of debug options, which cause GSK
- to print out different types of debugging information.
- <variablelist>
- <varlistentry>
- <term>renderer</term>
- <listitem><para>General renderer information</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>cairo</term>
- <listitem><para>cairo renderer information</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>opengl</term>
- <listitem><para>OpenGL renderer information</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>shaders</term>
- <listitem><para>Shaders</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>ssurface</term>
- <listitem><para>Surfaces</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>vulkan</term>
- <listitem><para>Vulkan renderer information</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>fallback</term>
- <listitem><para>Information about fallbacks</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>glyphcache</term>
- <listitem><para>Information about glyph caching</para></listitem>
- </varlistentry>
- </variablelist>
- A number of options affect behavior instead of logging:
- <variablelist>
- <varlistentry>
- <term>diff</term>
- <listitem><para>Show differences</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>geometry</term>
- <listitem><para>Show borders</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>full-redraw</term>
- <listitem><para>Force full redraws for every frame</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>sync</term>
- <listitem><para>Sync after each frame</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>vulkan-staging-image</term>
- <listitem><para>Use a staging image for Vulkan texture upload</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>vulkan-staging-buffer</term>
- <listitem><para>Use a staging buffer for Vulkan texture upload</para></listitem>
- </varlistentry>
- </variablelist>
- The special value <literal>all</literal> can be used to turn on all
- debug options. The special value <literal>help</literal> can be used
- to obtain a list of all supported debug options.
- </para>
-</formalpara>
-
-<formalpara>
- <title><envar>GDK_BACKEND</envar></title>
-
- <para>
- If set, selects the GDK backend to use. Selecting a backend requires that
- GTK is compiled with support for that backend. The following backends can
- be selected, provided they are included in the GDK libraries you are using:
- <variablelist>
-
- <varlistentry>
- <term>quartz</term>
- <listitem><para>Selects the native Quartz backend</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>win32</term>
- <listitem><para>Selects the native backend for Microsoft Windows</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>x11</term>
- <listitem><para>Selects the native backend for connecting to X11 servers.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>broadway</term>
- <listitem><para>Selects the Broadway backend for display in web browsers</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>wayland</term>
- <listitem><para>Selects the Wayland backend for connecting to Wayland display servers</para></listitem>
- </varlistentry>
-
- </variablelist>
- Since 3.10, this environment variable can contain a comma-separated list
- of backend names, which are tried in order. The list may also contain
- a *, which means: try all remaining backends. The special value "help" can
- be used to make GDK print out a list of all available backends.
- For more information about selecting backends, see the gdk_display_manager_get() function.
- </para>
-</formalpara>
-
-<formalpara>
- <title><envar>GDK_VULKAN_DEVICE</envar></title>
-
- <para>
- This variable can be set to the index of a Vulkan device to override the
- default selection of the device that is used for Vulkan rendering.
- The special value <literal>list</literal> can be used to obtain a list
- of all Vulkan devices.
- </para>
-</formalpara>
-
-<formalpara>
- <title><envar>GSK_RENDERER</envar></title>
-
- <para>
- If set, selects the GSK renderer to use. The following renderers can
- be selected, provided they are included in the GTK library you are using
- and the GDK backend supports them:
- <variablelist>
-
- <varlistentry>
- <term>help</term>
- <listitem><para>Prints information about available options</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>broadway</term>
- <listitem><para>Selects the Broadway-backend specific renderer</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>cairo</term>
- <listitem><para>Selects the fallback Cairo renderer</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>gl</term>
- <listitem><para>Selects the default OpenGL renderer</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>vulkan</term>
- <listitem><para>Selects the Vulkan renderer</para></listitem>
- </varlistentry>
-
- </variablelist>
- </para>
-</formalpara>
-
-<formalpara>
- <title><envar>GTK_CSD</envar></title>
-
- <para>
- The default value of this environment variable is 1. If changed to 0, this
- disables the default use of client-side decorations on GTK windows, thus
- making the window manager responsible for drawing the decorations of
- windows that do not have a custom titlebar widget.
- </para>
- <para>
- CSD is always used for windows with a custom titlebar widget set, as the WM
- should not draw another titlebar or other decorations around the custom one.
- </para>
-</formalpara>
-
-<formalpara>
- <title><envar>XDG_DATA_HOME</envar>, <envar>XDG_DATA_DIRS</envar></title>
-
- <para>
- GTK uses these environment variables to locate icon themes
- and MIME information. For more information, see
- <ulink url="https://freedesktop.org/Standards/icon-theme-spec">Icon Theme Specification</ulink>,
- the <ulink url="https://freedesktop.org/Standards/shared-mime-info-spec">Shared MIME-info Database</ulink>
- and the <ulink url="https://freedesktop.org/Standards/basedir-spec">Base Directory Specification</ulink>.
- </para>
-</formalpara>
-
-<formalpara>
- <title><envar>DESKTOP_STARTUP_ID</envar></title>
-
- <para>
- GTK uses this environment variable to provide startup notification
- according to the <ulink url="https://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt">Startup Notification Spec</ulink>.
- Following the specification, GTK unsets this variable after reading
- it (to keep it from leaking to child processes). So, if you need its
- value for your own purposes, you have to read it before calling
- gtk_init().
- </para>
-</formalpara>
-
-</refsect2>
-
-<refsect2 id="interactive-debugging">
-<title>Interactive debugging</title>
-
- <inlinegraphic fileref="inspector.png" format="PNG"></inlinegraphic>
-
- <para>
- GTK includes an interactive debugger, called the GTK Inspector, which
- lets you explore the widget tree of any GTK application at runtime, as
- well as tweak the theme and trigger visual debugging aids. You can
- easily try out changes at runtime before putting them into the code.
- </para>
- <para>
- Note that the GTK inspector can only show GTK internals. It can not
- understand the application-specific logic of a GTK application. Also,
- the fact that the GTK inspector is running in the application process
- limits what it can do. It is meant as a complement to full-blown debuggers
- and system tracing facilities such as DTrace, not as a replacement.
- </para>
- <para>
- To enable the GTK inspector, you can use the Control-Shift-I or
- Control-Shift-D keyboard shortcuts, or set the
- <envar>GTK_DEBUG=interactive</envar> environment variable.
- </para>
- <para>
- There are a few more environment variables that can be set to influence
- how the inspector renders its UI. <envar>GTK_INSPECTOR_DISPLAY</envar> and
- <envar>GTK_INSPECTOR_RENDERER</envar> determine the GDK display and
- the GSK renderer that the inspector is using.
- </para>
-
- <para>
- In some situations, it may be inappropriate to give users access to the
- GTK inspector. The keyboard shortcuts can be disabled with the
- `enable-inspector-keybinding` key in the `org.gtk.Settings.Debug`
- GSettings schema.
- </para>
-
-</refsect2>
-
-<refsect2 id="profiling">
- <title>Profiling</title>
-
- <para>
- GTK supports profiling with sysprof. It exports timing information
- about frameclock phases and various characteristics of GskRenders
- in a format that can be displayed by sysprof or GNOME Builder.
- </para>
- <para>
- A simple way to capture data is to set the <envar>GTK_TRACE</envar>
- environment variable. When it is set, GTK will write profiling
- data to a file called
- <filename>gtk.<replaceable>PID</replaceable>.syscap</filename>.
- </para>
- <para>
- When launching the application from sysprof, it will set the
- <envar>SYSPROF_TRACE_FD</envar> environment variable to point
- GTK at a file descriptor to write profiling data to.
- </para>
- <para>
- When GtkApplication registers with D-Bus, it exports the
- <literal>org.gnome.Sysprof2.Profiler</literal> interface
- that lets sysprof request profiling data at runtime.
- </para>
-</refsect2>
-
-</refsect1>
-
-</refentry>
--- /dev/null
+<?xml version="1.0"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
+]>
+<refentry id="gtk-running">
+<refmeta>
+<refentrytitle>Running GTK Applications</refentrytitle>
+<manvolnum>3</manvolnum>
+<refmiscinfo>GTK Library</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+<refname>Running GTK Applications</refname>
+<refpurpose>
+How to run and debug your GTK application
+</refpurpose>
+</refnamediv>
+
+<refsect1>
+<title>Running and debugging GTK Applications</title>
+
+<refsect2>
+<title>Environment variables</title>
+
+<para>
+GTK inspects a number of environment variables in addition to standard
+variables like <envar>LANG</envar>, <envar>PATH</envar>, <envar>HOME</envar>
+or <envar>DISPLAY</envar>; mostly to determine paths to look for certain
+files. The <link linkend="x11-envar">X11</link>,
+<link linkend="win32-envar">Windows</link> and
+<link linkend="broadway-envar">Broadway</link> GDK backends use some
+additional environment variables.
+</para>
+
+<formalpara id="GTK-Debug-Options">
+ <title><envar>GTK_DEBUG</envar></title>
+
+ <para>
+ Unless GTK has been configured with <option>--enable-debug=no</option>,
+ this variable can be set to a list of debug options, which cause GTK
+ to print out different types of debugging information.
+ <variablelist>
+ <varlistentry>
+ <term>actions</term>
+ <listitem><para>Actions and menu models</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>builder</term>
+ <listitem><para>GtkBuilder support</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>geometry</term>
+ <listitem><para>Size allocation</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>icontheme</term>
+ <listitem><para>Icon themes</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>keybindings</term>
+ <listitem><para>Keybindings</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>modules</term>
+ <listitem><para>Loading of modules</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>printing</term>
+ <listitem><para>Printing support</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>size-request</term>
+ <listitem><para>Size requests</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>text</term>
+ <listitem><para>Text widget internals</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>tree</term>
+ <listitem><para>Tree widget internals</para></listitem>
+ </varlistentry>
+ </variablelist>
+ A number of keys are influencing behavior instead of just logging:
+ <variablelist>
+ <varlistentry>
+ <term>interactive</term>
+ <listitem><para>Open the <link linkend="interactive-debugging">interactive debugger</link></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>no-css-cache</term>
+ <listitem><para>Bypass caching for CSS style properties</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>touchscreen</term>
+ <listitem><para>Pretend the pointer is a touchscreen device</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>baselines</term>
+ <listitem><para>Show baselines</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>updates</term>
+ <listitem><para>Visual feedback about window updates</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>resize</term>
+ <listitem><para>Highlight resizing widgets</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>layout</term>
+ <listitem><para>Show layout borders</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>snapshot</term>
+ <listitem><para>Include debug render nodes in the generated snapshots</para></listitem>
+ </varlistentry>
+ </variablelist>
+ The special value <literal>all</literal> can be used to turn on all
+ debug options. The special value <literal>help</literal> can be used
+ to obtain a list of all supported debug options.
+ </para>
+</formalpara>
+
+<formalpara id="gtk-path">
+ <title><envar>GTK_PATH</envar></title>
+
+ <para>
+ Specifies a list of directories to search when GTK is looking for
+ dynamically loaded objects such as input method
+ modules and print backends. If the path to
+ the dynamically loaded object is given as an absolute path name,
+ then GTK loads it directly.
+ Otherwise, GTK goes in turn through the directories in <envar>GTK_PATH</envar>,
+ followed by the directory <filename>.gtk-4.0</filename> in the user's
+ home directory, followed by the system default directory,
+ which is <filename><replaceable>libdir</replaceable>/gtk-4.0/modules</filename>.
+ (If <envar>GTK_EXE_PREFIX</envar> is defined, <replaceable>libdir</replaceable> is
+ <filename>$GTK_EXE_PREFIX/lib</filename>. Otherwise it is the libdir
+ specified when GTK was configured, usually
+ <filename>/usr/lib</filename>, or
+ <filename>/usr/local/lib</filename>.)
+ For each directory in this list, GTK actually looks in a
+ subdirectory
+ <filename><replaceable>directory</replaceable>/<replaceable>version</replaceable>/<replaceable>host</replaceable>/<replaceable>type</replaceable></filename>
+ Where <replaceable>version</replaceable> is derived from the
+ version of GTK (use <literal>pkg-config
+ --variable=gtk_binary_version gtk4</literal> to determine this from a
+ script), <replaceable>host</replaceable> is the architecture on
+ which GTK was built. (use <literal>pkg-config
+ --variable=gtk_host gtk4</literal> to determine this from a
+ script), and <replaceable>type</replaceable> is a directory
+ specific to the type of modules; currently it can be
+ <literal>modules</literal>, <literal>engines</literal>,
+ <literal>immodules</literal>, <literal>filesystems</literal> or
+ <literal>printbackends</literal>, corresponding to the types of
+ modules mentioned above. Either <replaceable>version</replaceable>,
+ <replaceable>host</replaceable>, or both may be omitted. GTK looks
+ first in the most specific directory, then in directories with
+ fewer components.
+ The components of GTK_PATH are separated by the ':' character on
+ Linux and Unix, and the ';' character on Windows.
+ </para>
+ <warning>
+ Note that this environment variable is read by GTK 2.x and GTK 3.x too,
+ which makes it unsuitable for setting it system-wide (or session-wide),
+ since doing so will cause applications using different GTK versions
+ to see incompatible modules.
+ </warning>
+</formalpara>
+
+<formalpara>
+ <title><envar>GTK_IM_MODULE</envar></title>
+
+ <para>
+ Specifies an IM module to use in preference to the one determined
+ from the locale. If this isn't set and you are running on the system
+ that enables <literal>XSETTINGS</literal> and has a value in
+ <literal>Gtk/IMModule</literal>, that will be used for the default
+ IM module.
+ This also can be a colon-separated list of input-methods, which
+ GTK will try in turn until it finds one available on the system.
+ </para>
+</formalpara>
+
+<formalpara>
+ <title><envar>GTK_EXE_PREFIX</envar></title>
+
+ <para>
+ If set, GTK uses <filename>$GTK_EXE_PREFIX/lib</filename> instead of
+ the libdir configured when GTK was compiled.
+ </para>
+</formalpara>
+
+<formalpara>
+ <title><envar>GTK_DATA_PREFIX</envar></title>
+
+ <para>
+ If set, makes GTK use <filename>$GTK_DATA_PREFIX</filename>
+ instead of the prefix configured when GTK was compiled.
+ </para>
+</formalpara>
+
+<formalpara>
+ <title><envar>GTK_THEME</envar></title>
+
+ <para>
+ If set, makes GTK use the named theme instead of the theme
+ that is specified by the gtk-theme-name setting. This is intended
+ mainly for easy debugging of theme issues.
+ </para>
+ <para>
+ It is also possible to specify a theme variant to load, by appending
+ the variant name with a colon, like this: `GTK_THEME=Adwaita:dark`.
+ </para>
+</formalpara>
+
+<para>
+The following environment variables are used by GdkPixbuf, GDK or
+Pango, not by GTK itself, but we list them here for completeness
+nevertheless.
+</para>
+
+<formalpara>
+ <title><envar>GDK_PIXBUF_MODULE_FILE</envar></title>
+
+ <para>
+ Specifies the file listing the GdkPixbuf loader modules to load.
+ This environment variable overrides the default value
+ <filename><replaceable>libdir</replaceable>/gtk-4.0/4.0.0/loaders.cache</filename>
+ (<replaceable>libdir</replaceable> is the sysconfdir specified when
+ GTK was configured, usually <filename>/usr/local/lib</filename>.)
+ </para>
+ <para>
+ The <filename>loaders.cache</filename> file is generated by the
+ <command>gdk-pixbuf-query-loaders</command> utility.
+ </para>
+ </formalpara>
+
+<formalpara id="GDK-Debug-Options">
+ <title><envar>GDK_DEBUG</envar></title>
+
+ <para>
+ If GTK has been configured with <option>--enable-debug=yes</option>,
+ this variable can be set to a list of debug options, which cause GDK
+ to print out different types of debugging information.
+ <variablelist>
+ <varlistentry>
+ <term>cursor</term>
+ <listitem><para>Information about cursor objects (only win32)</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>eventloop</term>
+ <listitem><para>Information about event loop operation (mostly Quartz)</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>misc</term>
+ <listitem><para>Miscellaneous information</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>frames</term>
+ <listitem><para>Information about the frame clock</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>settings</term>
+ <listitem><para>Information about xsettings</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>selection</term>
+ <listitem><para>Information about selections</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>clipboard</term>
+ <listitem><para>Information about clipboards</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>dnd</term>
+ <listitem><para>Information about drag-and-drop</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>opengl</term>
+ <listitem><para>Information about OpenGL</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>vulkan</term>
+ <listitem><para>Information about Vulkan</para></listitem>
+ </varlistentry>
+ </variablelist>
+ A number of options affect behavior instead of logging:
+ <variablelist>
+ <varlistentry>
+ <term>nograbs</term>
+ <listitem><para>Turn off all pointer and keyboard grabs</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>gl-disable</term>
+ <listitem><para>Disable OpenGL support</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>gl-software</term>
+ <listitem><para>Force OpenGL software rendering</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>gl-texture-rect</term>
+ <listitem><para>Use the OpenGL texture rectangle extension, if available</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>gl-legacy</term>
+ <listitem><para>Use a legacy OpenGL context</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>gl-gles</term>
+ <listitem><para>Use a GLES OpenGL context</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>vulkan-disable</term>
+ <listitem><para>Disable Vulkan support</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>vulkan-validate</term>
+ <listitem><para>Load the Vulkan validation layer, if available</para></listitem>
+ </varlistentry>
+ </variablelist>
+ The special value <literal>all</literal> can be used to turn on all
+ debug options. The special value <literal>help</literal> can be used
+ to obtain a list of all supported debug options.
+ </para>
+</formalpara>
+
+<formalpara id="GSK-Debug-Options">
+ <title><envar>GSK_DEBUG</envar></title>
+
+ <para>
+ If GTK has been configured with <option>--enable-debug=yes</option>,
+ this variable can be set to a list of debug options, which cause GSK
+ to print out different types of debugging information.
+ <variablelist>
+ <varlistentry>
+ <term>renderer</term>
+ <listitem><para>General renderer information</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>cairo</term>
+ <listitem><para>cairo renderer information</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>opengl</term>
+ <listitem><para>OpenGL renderer information</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>shaders</term>
+ <listitem><para>Shaders</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>ssurface</term>
+ <listitem><para>Surfaces</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>vulkan</term>
+ <listitem><para>Vulkan renderer information</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>fallback</term>
+ <listitem><para>Information about fallbacks</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>glyphcache</term>
+ <listitem><para>Information about glyph caching</para></listitem>
+ </varlistentry>
+ </variablelist>
+ A number of options affect behavior instead of logging:
+ <variablelist>
+ <varlistentry>
+ <term>diff</term>
+ <listitem><para>Show differences</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>geometry</term>
+ <listitem><para>Show borders</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>full-redraw</term>
+ <listitem><para>Force full redraws for every frame</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>sync</term>
+ <listitem><para>Sync after each frame</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>vulkan-staging-image</term>
+ <listitem><para>Use a staging image for Vulkan texture upload</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>vulkan-staging-buffer</term>
+ <listitem><para>Use a staging buffer for Vulkan texture upload</para></listitem>
+ </varlistentry>
+ </variablelist>
+ The special value <literal>all</literal> can be used to turn on all
+ debug options. The special value <literal>help</literal> can be used
+ to obtain a list of all supported debug options.
+ </para>
+</formalpara>
+
+<formalpara>
+ <title><envar>GDK_BACKEND</envar></title>
+
+ <para>
+ If set, selects the GDK backend to use. Selecting a backend requires that
+ GTK is compiled with support for that backend. The following backends can
+ be selected, provided they are included in the GDK libraries you are using:
+ <variablelist>
+
+ <varlistentry>
+ <term>quartz</term>
+ <listitem><para>Selects the native Quartz backend</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>win32</term>
+ <listitem><para>Selects the native backend for Microsoft Windows</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>x11</term>
+ <listitem><para>Selects the native backend for connecting to X11 servers.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>broadway</term>
+ <listitem><para>Selects the Broadway backend for display in web browsers</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>wayland</term>
+ <listitem><para>Selects the Wayland backend for connecting to Wayland display servers</para></listitem>
+ </varlistentry>
+
+ </variablelist>
+ Since 3.10, this environment variable can contain a comma-separated list
+ of backend names, which are tried in order. The list may also contain
+ a *, which means: try all remaining backends. The special value "help" can
+ be used to make GDK print out a list of all available backends.
+ For more information about selecting backends, see the gdk_display_manager_get() function.
+ </para>
+</formalpara>
+
+<formalpara>
+ <title><envar>GDK_VULKAN_DEVICE</envar></title>
+
+ <para>
+ This variable can be set to the index of a Vulkan device to override the
+ default selection of the device that is used for Vulkan rendering.
+ The special value <literal>list</literal> can be used to obtain a list
+ of all Vulkan devices.
+ </para>
+</formalpara>
+
+<formalpara>
+ <title><envar>GSK_RENDERER</envar></title>
+
+ <para>
+ If set, selects the GSK renderer to use. The following renderers can
+ be selected, provided they are included in the GTK library you are using
+ and the GDK backend supports them:
+ <variablelist>
+
+ <varlistentry>
+ <term>help</term>
+ <listitem><para>Prints information about available options</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>broadway</term>
+ <listitem><para>Selects the Broadway-backend specific renderer</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>cairo</term>
+ <listitem><para>Selects the fallback Cairo renderer</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>gl</term>
+ <listitem><para>Selects the default OpenGL renderer</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>vulkan</term>
+ <listitem><para>Selects the Vulkan renderer</para></listitem>
+ </varlistentry>
+
+ </variablelist>
+ </para>
+</formalpara>
+
+<formalpara>
+ <title><envar>GTK_CSD</envar></title>
+
+ <para>
+ The default value of this environment variable is 1. If changed to 0, this
+ disables the default use of client-side decorations on GTK windows, thus
+ making the window manager responsible for drawing the decorations of
+ windows that do not have a custom titlebar widget.
+ </para>
+ <para>
+ CSD is always used for windows with a custom titlebar widget set, as the WM
+ should not draw another titlebar or other decorations around the custom one.
+ </para>
+</formalpara>
+
+<formalpara>
+ <title><envar>XDG_DATA_HOME</envar>, <envar>XDG_DATA_DIRS</envar></title>
+
+ <para>
+ GTK uses these environment variables to locate icon themes
+ and MIME information. For more information, see
+ <ulink url="https://freedesktop.org/Standards/icon-theme-spec">Icon Theme Specification</ulink>,
+ the <ulink url="https://freedesktop.org/Standards/shared-mime-info-spec">Shared MIME-info Database</ulink>
+ and the <ulink url="https://freedesktop.org/Standards/basedir-spec">Base Directory Specification</ulink>.
+ </para>
+</formalpara>
+
+<formalpara>
+ <title><envar>DESKTOP_STARTUP_ID</envar></title>
+
+ <para>
+ GTK uses this environment variable to provide startup notification
+ according to the <ulink url="https://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt">Startup Notification Spec</ulink>.
+ Following the specification, GTK unsets this variable after reading
+ it (to keep it from leaking to child processes). So, if you need its
+ value for your own purposes, you have to read it before calling
+ gtk_init().
+ </para>
+</formalpara>
+
+</refsect2>
+
+<refsect2 id="interactive-debugging">
+<title>Interactive debugging</title>
+
+ <inlinegraphic fileref="inspector.png" format="PNG"></inlinegraphic>
+
+ <para>
+ GTK includes an interactive debugger, called the GTK Inspector, which
+ lets you explore the widget tree of any GTK application at runtime, as
+ well as tweak the theme and trigger visual debugging aids. You can
+ easily try out changes at runtime before putting them into the code.
+ </para>
+ <para>
+ Note that the GTK inspector can only show GTK internals. It can not
+ understand the application-specific logic of a GTK application. Also,
+ the fact that the GTK inspector is running in the application process
+ limits what it can do. It is meant as a complement to full-blown debuggers
+ and system tracing facilities such as DTrace, not as a replacement.
+ </para>
+ <para>
+ To enable the GTK inspector, you can use the Control-Shift-I or
+ Control-Shift-D keyboard shortcuts, or set the
+ <envar>GTK_DEBUG=interactive</envar> environment variable.
+ </para>
+ <para>
+ There are a few more environment variables that can be set to influence
+ how the inspector renders its UI. <envar>GTK_INSPECTOR_DISPLAY</envar> and
+ <envar>GTK_INSPECTOR_RENDERER</envar> determine the GDK display and
+ the GSK renderer that the inspector is using.
+ </para>
+
+ <para>
+ In some situations, it may be inappropriate to give users access to the
+ GTK inspector. The keyboard shortcuts can be disabled with the
+ `enable-inspector-keybinding` key in the `org.gtk.Settings.Debug`
+ GSettings schema.
+ </para>
+
+</refsect2>
+
+<refsect2 id="profiling">
+ <title>Profiling</title>
+
+ <para>
+ GTK supports profiling with sysprof. It exports timing information
+ about frameclock phases and various characteristics of GskRenders
+ in a format that can be displayed by sysprof or GNOME Builder.
+ </para>
+ <para>
+ A simple way to capture data is to set the <envar>GTK_TRACE</envar>
+ environment variable. When it is set, GTK will write profiling
+ data to a file called
+ <filename>gtk.<replaceable>PID</replaceable>.syscap</filename>.
+ </para>
+ <para>
+ When launching the application from sysprof, it will set the
+ <envar>SYSPROF_TRACE_FD</envar> environment variable to point
+ GTK at a file descriptor to write profiling data to.
+ </para>
+ <para>
+ When GtkApplication registers with D-Bus, it exports the
+ <literal>org.gnome.Sysprof2.Profiler</literal> interface
+ that lets sysprof request profiling data at runtime.
+ </para>
+</refsect2>
+
+</refsect1>
+
+</refentry>
+++ /dev/null
-<?xml version="1.0"?>
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
- "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
-]>
-<refentry id="TextWidget">
-<refmeta>
-<refentrytitle>Text Widget Overview</refentrytitle>
-<manvolnum>3</manvolnum>
-<refmiscinfo>GTK Library</refmiscinfo>
-</refmeta>
-
-<refnamediv>
-<refname>Text Widget Overview</refname>
-<refpurpose>Overview of GtkTextBuffer, GtkTextView, and friends</refpurpose>
-</refnamediv>
-
-<refsect1>
-<title>Conceptual Overview</title>
-
-<para>
-GTK has an extremely powerful framework for multiline text editing. The
-primary objects involved in the process are #GtkTextBuffer, which represents the
-text being edited, and #GtkTextView, a widget which can display a #GtkTextBuffer.
-Each buffer can be displayed by any number of views.
-</para>
-
-<para>
-One of the important things to remember about text in GTK is that it's in the
-UTF-8 encoding. This means that one character can be encoded as multiple
-bytes. Character counts are usually referred to as
-<firstterm>offsets</firstterm>, while byte counts are called
-<firstterm>indexes</firstterm>. If you confuse these two, things will work fine
-with ASCII, but as soon as your buffer contains multibyte characters, bad
-things will happen.
-</para>
-
-<para>
-Text in a buffer can be marked with <firstterm>tags</firstterm>. A tag is an
-attribute that can be applied to some range of text. For example, a tag might
-be called "bold" and make the text inside the tag bold. However, the tag
-concept is more general than that; tags don't have to affect appearance. They
-can instead affect the behavior of mouse and key presses, "lock" a range of
-text so the user can't edit it, or countless other things. A tag is
-represented by a #GtkTextTag object. One #GtkTextTag can be applied to any
-number of text ranges in any number of buffers.
-</para>
-
-<para>
-Each tag is stored in a #GtkTextTagTable. A tag table defines a set of
-tags that can be used together. Each buffer has one tag table associated with
-it; only tags from that tag table can be used with the buffer. A single tag
-table can be shared between multiple buffers, however.
-</para>
-
-<para>
-Tags can have names, which is convenient sometimes (for example, you can name
-your tag that makes things bold "bold"), but they can also be anonymous (which
-is convenient if you're creating tags on-the-fly).
-</para>
-
-<para>
-Most text manipulation is accomplished with <firstterm>iterators</firstterm>,
-represented by a #GtkTextIter. An iterator represents a position between two
-characters in the text buffer. #GtkTextIter is a struct designed to be
-allocated on the stack; it's guaranteed to be copiable by value and never
-contain any heap-allocated data. Iterators are not valid indefinitely;
-whenever the buffer is modified in a way that affects the number of characters
-in the buffer, all outstanding iterators become invalid. (Note that deleting
-5 characters and then reinserting 5 still invalidates iterators, though you
-end up with the same number of characters you pass through a state with a
-different number).
-</para>
-
-<para>
-Because of this, iterators can't be used to preserve positions across buffer
-modifications. To preserve a position, the #GtkTextMark object is ideal. You
-can think of a mark as an invisible cursor or insertion point; it floats in
-the buffer, saving a position. If the text surrounding the mark is deleted,
-the mark remains in the position the text once occupied; if text is inserted
-at the mark, the mark ends up either to the left or to the right of the new
-text, depending on its <firstterm>gravity</firstterm>. The standard text
-cursor in left-to-right languages is a mark with right gravity, because it
-stays to the right of inserted text.
-</para>
-
-<para>
-Like tags, marks can be either named or anonymous. There are two marks built-in
-to #GtkTextBuffer; these are named <literal>"insert"</literal> and
-<literal>"selection_bound"</literal> and refer to the insertion point and the
-boundary of the selection which is not the insertion point, respectively. If
-no text is selected, these two marks will be in the same position. You can
-manipulate what is selected and where the cursor appears by moving these
-marks around.
-<footnote>
-<para>
-If you want to place the cursor in response to a user action, be sure to use
-gtk_text_buffer_place_cursor(), which moves both at once without causing a
-temporary selection (moving one then the other temporarily selects the range in
-between the old and new positions).
-</para>
-</footnote>
-</para>
-
-<para>
-Text buffers always contain at least one line, but may be empty (that
-is, buffers can contain zero characters). The last line in the text
-buffer never ends in a line separator (such as newline); the other
-lines in the buffer always end in a line separator. Line separators
-count as characters when computing character counts and character
-offsets. Note that some Unicode line separators are represented with
-multiple bytes in UTF-8, and the two-character sequence "\r\n" is also
-considered a line separator.
-</para>
-
-<para>
-Text buffers support undo and redo if gtk_text_buffer_set_undo_enabled()
-has been set to %TRUE. Use gtk_text_buffer_undo() or gtk_text_buffer_redo()
-to perform the necessary action. Note that these operations are ignored if
-the buffer is not editable. Developers may want some operations to not be
-undoable. To do this, wrap your changes in
-gtk_text_buffer_begin_irreversible_action() and
-gtk_text_buffer_end_irreversible_action().
-</para>
-
-</refsect1>
-
-
-<refsect1>
-<title>Simple Example</title>
-
-<para>
-The simplest usage of #GtkTextView might look like this:
-<informalexample><programlisting>
- GtkWidget *view;
- GtkTextBuffer *buffer;
-
- view = gtk_text_view_new (<!-- -->);
-
- buffer = gtk_text_view_get_buffer (GTK_TEXT_VIEW (view));
-
- gtk_text_buffer_set_text (buffer, "Hello, this is some text", -1);
-
- /* Now you might put the view in a container and display it on the
- * screen; when the user edits the text, signals on the buffer
- * will be emitted, such as "changed", "insert_text", and so on.
- */
-</programlisting></informalexample>
-In many cases it's also convenient to first create the buffer with
-gtk_text_buffer_new(), then create a widget for that buffer with
-gtk_text_view_new_with_buffer(). Or you can change the buffer the widget
-displays after the widget is created with gtk_text_view_set_buffer().
-</para>
-
-</refsect1>
-
-<refsect1>
-<title>Example of Changing Text Attributes</title>
-
-<para>
-
-The way to affect text attributes in #GtkTextView is to
-apply tags that change the attributes for a region of text.
-For text features that come from the theme — such as font and
-foreground color — use CSS to override their default values.
-
-<informalexample><programlisting>
- GtkWidget *view;
- GtkTextBuffer *buffer;
- GtkTextIter start, end;
- PangoFontDescription *font_desc;
- GdkRGBA rgba;
- GtkTextTag *tag;
- GtkCssProvider *provider;
- GtkStyleContext *context;
-
- view = gtk_text_view_new (<!-- -->);
-
- buffer = gtk_text_view_get_buffer (GTK_TEXT_VIEW (view));
-
- gtk_text_buffer_set_text (buffer, "Hello, this is some text", -1);
-
- /* Change default font and color throughout the widget */
- provider = gtk_css_provider_new ();
- gtk_css_provider_load_from_data (provider,
- "textview {"
- " font: 15 serif;"
- " color: green;"
- "}",
- -1);
- context = gtk_widget_get_style_context (view);
- gtk_style_context_add_provider (context,
- GTK_STYLE_PROVIDER (provider),
- GTK_STYLE_PROVIDER_PRIORITY_APPLICATION);
-
- /* Change left margin throughout the widget */
- gtk_text_view_set_left_margin (GTK_TEXT_VIEW (view), 30);
-
- /* Use a tag to change the color for just one part of the widget */
- tag = gtk_text_buffer_create_tag (buffer, "blue_foreground",
- "foreground", "blue", NULL);
- gtk_text_buffer_get_iter_at_offset (buffer, &start, 7);
- gtk_text_buffer_get_iter_at_offset (buffer, &end, 12);
- gtk_text_buffer_apply_tag (buffer, tag, &start, &end);
-</programlisting></informalexample>
-
-</para>
-
-<para>
-The <application>gtk-demo</application> application that comes with
-GTK contains more example code for #GtkTextView.
-</para>
-
-</refsect1>
-
-</refentry>
--- /dev/null
+<?xml version="1.0"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
+]>
+<refentry id="TextWidget">
+<refmeta>
+<refentrytitle>Text Widget Overview</refentrytitle>
+<manvolnum>3</manvolnum>
+<refmiscinfo>GTK Library</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+<refname>Text Widget Overview</refname>
+<refpurpose>Overview of GtkTextBuffer, GtkTextView, and friends</refpurpose>
+</refnamediv>
+
+<refsect1>
+<title>Conceptual Overview</title>
+
+<para>
+GTK has an extremely powerful framework for multiline text editing. The
+primary objects involved in the process are #GtkTextBuffer, which represents the
+text being edited, and #GtkTextView, a widget which can display a #GtkTextBuffer.
+Each buffer can be displayed by any number of views.
+</para>
+
+<para>
+One of the important things to remember about text in GTK is that it's in the
+UTF-8 encoding. This means that one character can be encoded as multiple
+bytes. Character counts are usually referred to as
+<firstterm>offsets</firstterm>, while byte counts are called
+<firstterm>indexes</firstterm>. If you confuse these two, things will work fine
+with ASCII, but as soon as your buffer contains multibyte characters, bad
+things will happen.
+</para>
+
+<para>
+Text in a buffer can be marked with <firstterm>tags</firstterm>. A tag is an
+attribute that can be applied to some range of text. For example, a tag might
+be called "bold" and make the text inside the tag bold. However, the tag
+concept is more general than that; tags don't have to affect appearance. They
+can instead affect the behavior of mouse and key presses, "lock" a range of
+text so the user can't edit it, or countless other things. A tag is
+represented by a #GtkTextTag object. One #GtkTextTag can be applied to any
+number of text ranges in any number of buffers.
+</para>
+
+<para>
+Each tag is stored in a #GtkTextTagTable. A tag table defines a set of
+tags that can be used together. Each buffer has one tag table associated with
+it; only tags from that tag table can be used with the buffer. A single tag
+table can be shared between multiple buffers, however.
+</para>
+
+<para>
+Tags can have names, which is convenient sometimes (for example, you can name
+your tag that makes things bold "bold"), but they can also be anonymous (which
+is convenient if you're creating tags on-the-fly).
+</para>
+
+<para>
+Most text manipulation is accomplished with <firstterm>iterators</firstterm>,
+represented by a #GtkTextIter. An iterator represents a position between two
+characters in the text buffer. #GtkTextIter is a struct designed to be
+allocated on the stack; it's guaranteed to be copiable by value and never
+contain any heap-allocated data. Iterators are not valid indefinitely;
+whenever the buffer is modified in a way that affects the number of characters
+in the buffer, all outstanding iterators become invalid. (Note that deleting
+5 characters and then reinserting 5 still invalidates iterators, though you
+end up with the same number of characters you pass through a state with a
+different number).
+</para>
+
+<para>
+Because of this, iterators can't be used to preserve positions across buffer
+modifications. To preserve a position, the #GtkTextMark object is ideal. You
+can think of a mark as an invisible cursor or insertion point; it floats in
+the buffer, saving a position. If the text surrounding the mark is deleted,
+the mark remains in the position the text once occupied; if text is inserted
+at the mark, the mark ends up either to the left or to the right of the new
+text, depending on its <firstterm>gravity</firstterm>. The standard text
+cursor in left-to-right languages is a mark with right gravity, because it
+stays to the right of inserted text.
+</para>
+
+<para>
+Like tags, marks can be either named or anonymous. There are two marks built-in
+to #GtkTextBuffer; these are named <literal>"insert"</literal> and
+<literal>"selection_bound"</literal> and refer to the insertion point and the
+boundary of the selection which is not the insertion point, respectively. If
+no text is selected, these two marks will be in the same position. You can
+manipulate what is selected and where the cursor appears by moving these
+marks around.
+<footnote>
+<para>
+If you want to place the cursor in response to a user action, be sure to use
+gtk_text_buffer_place_cursor(), which moves both at once without causing a
+temporary selection (moving one then the other temporarily selects the range in
+between the old and new positions).
+</para>
+</footnote>
+</para>
+
+<para>
+Text buffers always contain at least one line, but may be empty (that
+is, buffers can contain zero characters). The last line in the text
+buffer never ends in a line separator (such as newline); the other
+lines in the buffer always end in a line separator. Line separators
+count as characters when computing character counts and character
+offsets. Note that some Unicode line separators are represented with
+multiple bytes in UTF-8, and the two-character sequence "\r\n" is also
+considered a line separator.
+</para>
+
+<para>
+Text buffers support undo and redo if gtk_text_buffer_set_undo_enabled()
+has been set to %TRUE. Use gtk_text_buffer_undo() or gtk_text_buffer_redo()
+to perform the necessary action. Note that these operations are ignored if
+the buffer is not editable. Developers may want some operations to not be
+undoable. To do this, wrap your changes in
+gtk_text_buffer_begin_irreversible_action() and
+gtk_text_buffer_end_irreversible_action().
+</para>
+
+</refsect1>
+
+
+<refsect1>
+<title>Simple Example</title>
+
+<para>
+The simplest usage of #GtkTextView might look like this:
+<informalexample><programlisting>
+ GtkWidget *view;
+ GtkTextBuffer *buffer;
+
+ view = gtk_text_view_new (<!-- -->);
+
+ buffer = gtk_text_view_get_buffer (GTK_TEXT_VIEW (view));
+
+ gtk_text_buffer_set_text (buffer, "Hello, this is some text", -1);
+
+ /* Now you might put the view in a container and display it on the
+ * screen; when the user edits the text, signals on the buffer
+ * will be emitted, such as "changed", "insert_text", and so on.
+ */
+</programlisting></informalexample>
+In many cases it's also convenient to first create the buffer with
+gtk_text_buffer_new(), then create a widget for that buffer with
+gtk_text_view_new_with_buffer(). Or you can change the buffer the widget
+displays after the widget is created with gtk_text_view_set_buffer().
+</para>
+
+</refsect1>
+
+<refsect1>
+<title>Example of Changing Text Attributes</title>
+
+<para>
+
+The way to affect text attributes in #GtkTextView is to
+apply tags that change the attributes for a region of text.
+For text features that come from the theme — such as font and
+foreground color — use CSS to override their default values.
+
+<informalexample><programlisting>
+ GtkWidget *view;
+ GtkTextBuffer *buffer;
+ GtkTextIter start, end;
+ PangoFontDescription *font_desc;
+ GdkRGBA rgba;
+ GtkTextTag *tag;
+ GtkCssProvider *provider;
+ GtkStyleContext *context;
+
+ view = gtk_text_view_new (<!-- -->);
+
+ buffer = gtk_text_view_get_buffer (GTK_TEXT_VIEW (view));
+
+ gtk_text_buffer_set_text (buffer, "Hello, this is some text", -1);
+
+ /* Change default font and color throughout the widget */
+ provider = gtk_css_provider_new ();
+ gtk_css_provider_load_from_data (provider,
+ "textview {"
+ " font: 15 serif;"
+ " color: green;"
+ "}",
+ -1);
+ context = gtk_widget_get_style_context (view);
+ gtk_style_context_add_provider (context,
+ GTK_STYLE_PROVIDER (provider),
+ GTK_STYLE_PROVIDER_PRIORITY_APPLICATION);
+
+ /* Change left margin throughout the widget */
+ gtk_text_view_set_left_margin (GTK_TEXT_VIEW (view), 30);
+
+ /* Use a tag to change the color for just one part of the widget */
+ tag = gtk_text_buffer_create_tag (buffer, "blue_foreground",
+ "foreground", "blue", NULL);
+ gtk_text_buffer_get_iter_at_offset (buffer, &start, 7);
+ gtk_text_buffer_get_iter_at_offset (buffer, &end, 12);
+ gtk_text_buffer_apply_tag (buffer, tag, &start, &end);
+</programlisting></informalexample>
+
+</para>
+
+<para>
+The <application>gtk-demo</application> application that comes with
+GTK contains more example code for #GtkTextView.
+</para>
+
+</refsect1>
+
+</refentry>
+++ /dev/null
-<?xml version="1.0"?>
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
- "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
-]>
-<refentry id="TreeWidget">
- <refmeta>
- <refentrytitle>Tree and List Widget Overview</refentrytitle>
- <manvolnum>3</manvolnum>
- <refmiscinfo>GTK Library</refmiscinfo>
- </refmeta>
-
- <refnamediv>
- <refname>Tree and List Widget Overview</refname>
- <refpurpose>Overview of GtkTreeModel, GtkTreeView, and friends</refpurpose>
- </refnamediv>
-
- <refsect1>
- <title>Overview</title>
- <para>
- To create a tree or list in GTK, use the #GtkTreeModel interface in
- conjunction with the #GtkTreeView widget. This widget is
- designed around a <firstterm>Model/View/Controller</firstterm>
- design and consists of four major parts:
- <simplelist>
- <member>The tree view widget (<structname>GtkTreeView</structname>)</member>
- <member>The view column (<structname>GtkTreeViewColumn</structname>)</member>
- <member>The cell renderers (<structname>GtkCellRenderer</structname> etc.)</member>
- <member>The model interface (<structname>GtkTreeModel</structname>)</member>
- </simplelist>
- The <emphasis>View</emphasis> is composed of the first three
- objects, while the last is the <emphasis>Model</emphasis>. One
- of the prime benefits of the MVC design is that multiple views
- can be created of a single model. For example, a model mapping
- the file system could be created for a file manager. Many views
- could be created to display various parts of the file system,
- but only one copy need be kept in memory.
- </para>
- <para>
- The purpose of the cell renderers is to provide extensibility to the
- widget and to allow multiple ways of rendering the same type of data.
- For example, consider how to render a boolean variable. Should it
- render it as a string of "True" or "False", "On" or "Off", or should
- it be rendered as a checkbox?
- </para>
- </refsect1>
- <refsect1>
- <title>Creating a model</title>
- <para>
- GTK provides two simple models that can be used: the #GtkListStore
- and the #GtkTreeStore. GtkListStore is used to model list widgets,
- while the GtkTreeStore models trees. It is possible to develop a new
- type of model, but the existing models should be satisfactory for all
- but the most specialized of situations. Creating the model is quite
- simple:
- </para>
- <informalexample><programlisting><![CDATA[
-GtkListStore *store = gtk_list_store_new (2, G_TYPE_STRING, G_TYPE_BOOLEAN);
-]]></programlisting></informalexample>
- <para>
- This creates a list store with two columns: a string column and a boolean
- column. Typically the 2 is never passed directly like that; usually an
- enum is created wherein the different columns are enumerated, followed by
- a token that represents the total number of columns. The next example will
- illustrate this, only using a tree store instead of a list store. Creating
- a tree store operates almost exactly the same.
- </para>
- <informalexample><programlisting><![CDATA[
-enum
-{
- TITLE_COLUMN,
- AUTHOR_COLUMN,
- CHECKED_COLUMN,
- N_COLUMNS
-};
-
-GtkTreeStore *store = gtk_tree_store_new (N_COLUMNS, /* Total number of columns */
- G_TYPE_STRING, /* Book title */
- G_TYPE_STRING, /* Author */
- G_TYPE_BOOLEAN); /* Is checked out? */
-]]></programlisting></informalexample>
- <para>
- Adding data to the model is done using gtk_tree_store_set() or
- gtk_list_store_set(), depending upon which sort of model was
- created. To do this, a #GtkTreeIter must be acquired. The iterator
- points to the location where data will be added.
- </para>
- <para>
- Once an iterator has been acquired, gtk_tree_store_set() is used to
- apply data to the part of the model that the iterator points to.
- Consider the following example:
- </para>
- <informalexample><programlisting><![CDATA[
-GtkTreeIter iter;
-
-gtk_tree_store_append (store, &iter, NULL); /* Acquire an iterator */
-
-gtk_tree_store_set (store, &iter,
- TITLE_COLUMN, "The Principle of Reason",
- AUTHOR_COLUMN, "Martin Heidegger",
- CHECKED_COLUMN, FALSE,
- -1);
-]]></programlisting></informalexample>
-
- <para>
- Notice that the last argument is -1. This is always done because
- this is a variable-argument function and it needs to know when to stop
- processing arguments. It can be used to set the data in any or all
- columns in a given row.
- </para>
- <para>
- The third argument to gtk_tree_store_append() is the parent iterator. It
- is used to add a row to a GtkTreeStore as a child of an existing row. This
- means that the new row will only be visible when its parent is visible and
- in its expanded state. Consider the following example:
- </para>
- <informalexample><programlisting><![CDATA[
-GtkTreeIter iter1; /* Parent iter */
-GtkTreeIter iter2; /* Child iter */
-
-gtk_tree_store_append (store, &iter1, NULL); /* Acquire a top-level iterator */
-gtk_tree_store_set (store, &iter1,
- TITLE_COLUMN, "The Art of Computer Programming",
- AUTHOR_COLUMN, "Donald E. Knuth",
- CHECKED_COLUMN, FALSE,
- -1);
-
-gtk_tree_store_append (store, &iter2, &iter1); /* Acquire a child iterator */
-gtk_tree_store_set (store, &iter2,
- TITLE_COLUMN, "Volume 1: Fundamental Algorithms",
- -1);
-
-gtk_tree_store_append (store, &iter2, &iter1);
-gtk_tree_store_set (store, &iter2,
- TITLE_COLUMN, "Volume 2: Seminumerical Algorithms",
- -1);
-
-gtk_tree_store_append (store, &iter2, &iter1);
-gtk_tree_store_set (store, &iter2,
- TITLE_COLUMN, "Volume 3: Sorting and Searching",
- -1);
-]]></programlisting></informalexample>
- </refsect1>
-
- <refsect1>
- <title>Creating the view component</title>
- <para>
- While there are several different models to choose from, there is
- only one view widget to deal with. It works with either the list
- or the tree store. Setting up a #GtkTreeView is not a difficult
- matter. It needs a #GtkTreeModel to know where to retrieve its data
- from.
- </para>
- <informalexample><programlisting><![CDATA[
-GtkWidget *tree;
-
-tree = gtk_tree_view_new_with_model (GTK_TREE_MODEL (store));
-]]></programlisting></informalexample>
-
- <refsect2>
- <title>Columns and cell renderers</title>
- <para>
- Once the #GtkTreeView widget has a model, it will need to know how
- to display the model. It does this with columns and cell renderers.
- </para>
- <para>
- Cell renderers are used to draw the data in the tree model in a
- way. There are a number of cell renderers that come with GTK,
- including the #GtkCellRendererText, #GtkCellRendererPixbuf and
- the #GtkCellRendererToggle.
- It is relatively easy to write a custom renderer.
- </para>
- <para>
- A #GtkTreeViewColumn is the object that GtkTreeView uses to organize
- the vertical columns in the tree view. It needs to know the name of
- the column to label for the user, what type of cell renderer to use,
- and which piece of data to retrieve from the model for a given row.
- </para>
- <informalexample><programlisting>
-GtkCellRenderer *renderer;
-GtkTreeViewColumn *column;
-
-renderer = gtk_cell_renderer_text_new (<!-- -->);
-column = gtk_tree_view_column_new_with_attributes ("Author",
- renderer,
- "text", AUTHOR_COLUMN,
- NULL);
-gtk_tree_view_append_column (GTK_TREE_VIEW (tree), column);
-</programlisting></informalexample>
- <para>
- At this point, all the steps in creating a displayable tree have been
- covered. The model is created, data is stored in it, a tree view is
- created and columns are added to it.
- </para>
- </refsect2>
-
- <refsect2>
- <title>Selection handling</title>
- <para>
- Most applications will need to not only deal with displaying data, but
- also receiving input events from users. To do this, simply get a
- reference to a selection object and connect to the
- #GtkTreeSelection::changed signal.
- </para>
- <informalexample><programlisting><![CDATA[
-/* Prototype for selection handler callback */
-static void tree_selection_changed_cb (GtkTreeSelection *selection, gpointer data);
-
-/* Setup the selection handler */
-GtkTreeSelection *select;
-
-select = gtk_tree_view_get_selection (GTK_TREE_VIEW (tree));
-gtk_tree_selection_set_mode (select, GTK_SELECTION_SINGLE);
-g_signal_connect (G_OBJECT (select), "changed",
- G_CALLBACK (tree_selection_changed_cb),
- NULL);
-]]></programlisting></informalexample>
- <para>
- Then to retrieve data for the row selected:
- </para>
- <informalexample><programlisting><![CDATA[
-static void
-tree_selection_changed_cb (GtkTreeSelection *selection, gpointer data)
-{
- GtkTreeIter iter;
- GtkTreeModel *model;
- gchar *author;
-
- if (gtk_tree_selection_get_selected (selection, &model, &iter))
- {
- gtk_tree_model_get (model, &iter, AUTHOR_COLUMN, &author, -1);
-
- g_print ("You selected a book by %s\n", author);
-
- g_free (author);
- }
-}
-]]></programlisting></informalexample>
- </refsect2>
- </refsect1>
-
- <refsect1>
- <title>Simple Example</title>
- <para>
- Here is a simple example of using a #GtkTreeView widget in context
- of the other widgets. It simply creates a simple model and view,
- and puts them together. Note that the model is never populated
- with data — that is left as an exercise for the reader.
- More information can be found on this in the #GtkTreeModel section.
- <informalexample><programlisting>
-enum
-{
- TITLE_COLUMN,
- AUTHOR_COLUMN,
- CHECKED_COLUMN,
- N_COLUMNS
-};
-
-void
-setup_tree (void)
-{
- GtkTreeStore *store;
- GtkWidget *tree;
- GtkTreeViewColumn *column;
- GtkCellRenderer *renderer;
-
- /* Create a model. We are using the store model for now, though we
- * could use any other GtkTreeModel */
- store = gtk_tree_store_new (N_COLUMNS,
- G_TYPE_STRING,
- G_TYPE_STRING,
- G_TYPE_BOOLEAN);
-
- /* custom function to fill the model with data */
- populate_tree_model (store);
-
- /* Create a view */
- tree = gtk_tree_view_new_with_model (GTK_TREE_MODEL (store));
-
- /* The view now holds a reference. We can get rid of our own
- * reference */
- g_object_unref (G_OBJECT (store));
-
- /* Create a cell render and arbitrarily make it red for demonstration
- * purposes */
- renderer = gtk_cell_renderer_text_new (<!-- -->);
- g_object_set (G_OBJECT (renderer),
- "foreground", "red",
- NULL);
-
- /* Create a column, associating the "text" attribute of the
- * cell_renderer to the first column of the model */
- column = gtk_tree_view_column_new_with_attributes ("Author", renderer,
- "text", AUTHOR_COLUMN,
- NULL);
-
- /* Add the column to the view. */
- gtk_tree_view_append_column (GTK_TREE_VIEW (tree), column);
-
- /* Second column.. title of the book. */
- renderer = gtk_cell_renderer_text_new (<!-- -->);
- column = gtk_tree_view_column_new_with_attributes ("Title",
- renderer,
- "text", TITLE_COLUMN,
- NULL);
- gtk_tree_view_append_column (GTK_TREE_VIEW (tree), column);
-
- /* Last column.. whether a book is checked out. */
- renderer = gtk_cell_renderer_toggle_new (<!-- -->);
- column = gtk_tree_view_column_new_with_attributes ("Checked out",
- renderer,
- "active", CHECKED_COLUMN,
- NULL);
- gtk_tree_view_append_column (GTK_TREE_VIEW (tree), column);
-
- /* Now we can manipulate the view just like any other GTK widget */
- ...
-}
- </programlisting></informalexample>
- </para>
- </refsect1>
-</refentry>
--- /dev/null
+<?xml version="1.0"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
+]>
+<refentry id="TreeWidget">
+ <refmeta>
+ <refentrytitle>Tree and List Widget Overview</refentrytitle>
+ <manvolnum>3</manvolnum>
+ <refmiscinfo>GTK Library</refmiscinfo>
+ </refmeta>
+
+ <refnamediv>
+ <refname>Tree and List Widget Overview</refname>
+ <refpurpose>Overview of GtkTreeModel, GtkTreeView, and friends</refpurpose>
+ </refnamediv>
+
+ <refsect1>
+ <title>Overview</title>
+ <para>
+ To create a tree or list in GTK, use the #GtkTreeModel interface in
+ conjunction with the #GtkTreeView widget. This widget is
+ designed around a <firstterm>Model/View/Controller</firstterm>
+ design and consists of four major parts:
+ <simplelist>
+ <member>The tree view widget (<structname>GtkTreeView</structname>)</member>
+ <member>The view column (<structname>GtkTreeViewColumn</structname>)</member>
+ <member>The cell renderers (<structname>GtkCellRenderer</structname> etc.)</member>
+ <member>The model interface (<structname>GtkTreeModel</structname>)</member>
+ </simplelist>
+ The <emphasis>View</emphasis> is composed of the first three
+ objects, while the last is the <emphasis>Model</emphasis>. One
+ of the prime benefits of the MVC design is that multiple views
+ can be created of a single model. For example, a model mapping
+ the file system could be created for a file manager. Many views
+ could be created to display various parts of the file system,
+ but only one copy need be kept in memory.
+ </para>
+ <para>
+ The purpose of the cell renderers is to provide extensibility to the
+ widget and to allow multiple ways of rendering the same type of data.
+ For example, consider how to render a boolean variable. Should it
+ render it as a string of "True" or "False", "On" or "Off", or should
+ it be rendered as a checkbox?
+ </para>
+ </refsect1>
+ <refsect1>
+ <title>Creating a model</title>
+ <para>
+ GTK provides two simple models that can be used: the #GtkListStore
+ and the #GtkTreeStore. GtkListStore is used to model list widgets,
+ while the GtkTreeStore models trees. It is possible to develop a new
+ type of model, but the existing models should be satisfactory for all
+ but the most specialized of situations. Creating the model is quite
+ simple:
+ </para>
+ <informalexample><programlisting><![CDATA[
+GtkListStore *store = gtk_list_store_new (2, G_TYPE_STRING, G_TYPE_BOOLEAN);
+]]></programlisting></informalexample>
+ <para>
+ This creates a list store with two columns: a string column and a boolean
+ column. Typically the 2 is never passed directly like that; usually an
+ enum is created wherein the different columns are enumerated, followed by
+ a token that represents the total number of columns. The next example will
+ illustrate this, only using a tree store instead of a list store. Creating
+ a tree store operates almost exactly the same.
+ </para>
+ <informalexample><programlisting><![CDATA[
+enum
+{
+ TITLE_COLUMN,
+ AUTHOR_COLUMN,
+ CHECKED_COLUMN,
+ N_COLUMNS
+};
+
+GtkTreeStore *store = gtk_tree_store_new (N_COLUMNS, /* Total number of columns */
+ G_TYPE_STRING, /* Book title */
+ G_TYPE_STRING, /* Author */
+ G_TYPE_BOOLEAN); /* Is checked out? */
+]]></programlisting></informalexample>
+ <para>
+ Adding data to the model is done using gtk_tree_store_set() or
+ gtk_list_store_set(), depending upon which sort of model was
+ created. To do this, a #GtkTreeIter must be acquired. The iterator
+ points to the location where data will be added.
+ </para>
+ <para>
+ Once an iterator has been acquired, gtk_tree_store_set() is used to
+ apply data to the part of the model that the iterator points to.
+ Consider the following example:
+ </para>
+ <informalexample><programlisting><![CDATA[
+GtkTreeIter iter;
+
+gtk_tree_store_append (store, &iter, NULL); /* Acquire an iterator */
+
+gtk_tree_store_set (store, &iter,
+ TITLE_COLUMN, "The Principle of Reason",
+ AUTHOR_COLUMN, "Martin Heidegger",
+ CHECKED_COLUMN, FALSE,
+ -1);
+]]></programlisting></informalexample>
+
+ <para>
+ Notice that the last argument is -1. This is always done because
+ this is a variable-argument function and it needs to know when to stop
+ processing arguments. It can be used to set the data in any or all
+ columns in a given row.
+ </para>
+ <para>
+ The third argument to gtk_tree_store_append() is the parent iterator. It
+ is used to add a row to a GtkTreeStore as a child of an existing row. This
+ means that the new row will only be visible when its parent is visible and
+ in its expanded state. Consider the following example:
+ </para>
+ <informalexample><programlisting><![CDATA[
+GtkTreeIter iter1; /* Parent iter */
+GtkTreeIter iter2; /* Child iter */
+
+gtk_tree_store_append (store, &iter1, NULL); /* Acquire a top-level iterator */
+gtk_tree_store_set (store, &iter1,
+ TITLE_COLUMN, "The Art of Computer Programming",
+ AUTHOR_COLUMN, "Donald E. Knuth",
+ CHECKED_COLUMN, FALSE,
+ -1);
+
+gtk_tree_store_append (store, &iter2, &iter1); /* Acquire a child iterator */
+gtk_tree_store_set (store, &iter2,
+ TITLE_COLUMN, "Volume 1: Fundamental Algorithms",
+ -1);
+
+gtk_tree_store_append (store, &iter2, &iter1);
+gtk_tree_store_set (store, &iter2,
+ TITLE_COLUMN, "Volume 2: Seminumerical Algorithms",
+ -1);
+
+gtk_tree_store_append (store, &iter2, &iter1);
+gtk_tree_store_set (store, &iter2,
+ TITLE_COLUMN, "Volume 3: Sorting and Searching",
+ -1);
+]]></programlisting></informalexample>
+ </refsect1>
+
+ <refsect1>
+ <title>Creating the view component</title>
+ <para>
+ While there are several different models to choose from, there is
+ only one view widget to deal with. It works with either the list
+ or the tree store. Setting up a #GtkTreeView is not a difficult
+ matter. It needs a #GtkTreeModel to know where to retrieve its data
+ from.
+ </para>
+ <informalexample><programlisting><![CDATA[
+GtkWidget *tree;
+
+tree = gtk_tree_view_new_with_model (GTK_TREE_MODEL (store));
+]]></programlisting></informalexample>
+
+ <refsect2>
+ <title>Columns and cell renderers</title>
+ <para>
+ Once the #GtkTreeView widget has a model, it will need to know how
+ to display the model. It does this with columns and cell renderers.
+ </para>
+ <para>
+ Cell renderers are used to draw the data in the tree model in a
+ way. There are a number of cell renderers that come with GTK,
+ including the #GtkCellRendererText, #GtkCellRendererPixbuf and
+ the #GtkCellRendererToggle.
+ It is relatively easy to write a custom renderer.
+ </para>
+ <para>
+ A #GtkTreeViewColumn is the object that GtkTreeView uses to organize
+ the vertical columns in the tree view. It needs to know the name of
+ the column to label for the user, what type of cell renderer to use,
+ and which piece of data to retrieve from the model for a given row.
+ </para>
+ <informalexample><programlisting>
+GtkCellRenderer *renderer;
+GtkTreeViewColumn *column;
+
+renderer = gtk_cell_renderer_text_new (<!-- -->);
+column = gtk_tree_view_column_new_with_attributes ("Author",
+ renderer,
+ "text", AUTHOR_COLUMN,
+ NULL);
+gtk_tree_view_append_column (GTK_TREE_VIEW (tree), column);
+</programlisting></informalexample>
+ <para>
+ At this point, all the steps in creating a displayable tree have been
+ covered. The model is created, data is stored in it, a tree view is
+ created and columns are added to it.
+ </para>
+ </refsect2>
+
+ <refsect2>
+ <title>Selection handling</title>
+ <para>
+ Most applications will need to not only deal with displaying data, but
+ also receiving input events from users. To do this, simply get a
+ reference to a selection object and connect to the
+ #GtkTreeSelection::changed signal.
+ </para>
+ <informalexample><programlisting><![CDATA[
+/* Prototype for selection handler callback */
+static void tree_selection_changed_cb (GtkTreeSelection *selection, gpointer data);
+
+/* Setup the selection handler */
+GtkTreeSelection *select;
+
+select = gtk_tree_view_get_selection (GTK_TREE_VIEW (tree));
+gtk_tree_selection_set_mode (select, GTK_SELECTION_SINGLE);
+g_signal_connect (G_OBJECT (select), "changed",
+ G_CALLBACK (tree_selection_changed_cb),
+ NULL);
+]]></programlisting></informalexample>
+ <para>
+ Then to retrieve data for the row selected:
+ </para>
+ <informalexample><programlisting><![CDATA[
+static void
+tree_selection_changed_cb (GtkTreeSelection *selection, gpointer data)
+{
+ GtkTreeIter iter;
+ GtkTreeModel *model;
+ gchar *author;
+
+ if (gtk_tree_selection_get_selected (selection, &model, &iter))
+ {
+ gtk_tree_model_get (model, &iter, AUTHOR_COLUMN, &author, -1);
+
+ g_print ("You selected a book by %s\n", author);
+
+ g_free (author);
+ }
+}
+]]></programlisting></informalexample>
+ </refsect2>
+ </refsect1>
+
+ <refsect1>
+ <title>Simple Example</title>
+ <para>
+ Here is a simple example of using a #GtkTreeView widget in context
+ of the other widgets. It simply creates a simple model and view,
+ and puts them together. Note that the model is never populated
+ with data — that is left as an exercise for the reader.
+ More information can be found on this in the #GtkTreeModel section.
+ <informalexample><programlisting>
+enum
+{
+ TITLE_COLUMN,
+ AUTHOR_COLUMN,
+ CHECKED_COLUMN,
+ N_COLUMNS
+};
+
+void
+setup_tree (void)
+{
+ GtkTreeStore *store;
+ GtkWidget *tree;
+ GtkTreeViewColumn *column;
+ GtkCellRenderer *renderer;
+
+ /* Create a model. We are using the store model for now, though we
+ * could use any other GtkTreeModel */
+ store = gtk_tree_store_new (N_COLUMNS,
+ G_TYPE_STRING,
+ G_TYPE_STRING,
+ G_TYPE_BOOLEAN);
+
+ /* custom function to fill the model with data */
+ populate_tree_model (store);
+
+ /* Create a view */
+ tree = gtk_tree_view_new_with_model (GTK_TREE_MODEL (store));
+
+ /* The view now holds a reference. We can get rid of our own
+ * reference */
+ g_object_unref (G_OBJECT (store));
+
+ /* Create a cell render and arbitrarily make it red for demonstration
+ * purposes */
+ renderer = gtk_cell_renderer_text_new (<!-- -->);
+ g_object_set (G_OBJECT (renderer),
+ "foreground", "red",
+ NULL);
+
+ /* Create a column, associating the "text" attribute of the
+ * cell_renderer to the first column of the model */
+ column = gtk_tree_view_column_new_with_attributes ("Author", renderer,
+ "text", AUTHOR_COLUMN,
+ NULL);
+
+ /* Add the column to the view. */
+ gtk_tree_view_append_column (GTK_TREE_VIEW (tree), column);
+
+ /* Second column.. title of the book. */
+ renderer = gtk_cell_renderer_text_new (<!-- -->);
+ column = gtk_tree_view_column_new_with_attributes ("Title",
+ renderer,
+ "text", TITLE_COLUMN,
+ NULL);
+ gtk_tree_view_append_column (GTK_TREE_VIEW (tree), column);
+
+ /* Last column.. whether a book is checked out. */
+ renderer = gtk_cell_renderer_toggle_new (<!-- -->);
+ column = gtk_tree_view_column_new_with_attributes ("Checked out",
+ renderer,
+ "active", CHECKED_COLUMN,
+ NULL);
+ gtk_tree_view_append_column (GTK_TREE_VIEW (tree), column);
+
+ /* Now we can manipulate the view just like any other GTK widget */
+ ...
+}
+ </programlisting></informalexample>
+ </para>
+ </refsect1>
+</refentry>
+++ /dev/null
-<?xml version="1.0"?>
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
- "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
-]>
-<refentry id="gtk-windows">
-<refmeta>
-<refentrytitle>Using GTK on Windows</refentrytitle>
-<manvolnum>3</manvolnum>
-<refmiscinfo>GTK Library</refmiscinfo>
-</refmeta>
-
-<refnamediv>
-<refname>Using GTK on Windows</refname>
-<refpurpose>
-Windows-specific aspects of using GTK
-</refpurpose>
-</refnamediv>
-
-<refsect1>
-<title>Using GTK on Windows</title>
-
-<para>
-The Windows port of GTK is an implementation of GDK (and therefore GTK)
-on top of the Win32 API. When compiling GTK on Windows, this backend is
-the default.
-</para>
-
-<refsect2 id="win32-cmdline">
-<title>Windows-specific commandline options</title>
-
-<para>
-The Windows GDK backend can be influenced with some
-additional command line arguments.
-</para>
-
-<formalpara>
-<title><systemitem>--sync</systemitem></title>
-
-<para>
-Don't batch GDI requests. This might be a marginally useful option for
-debugging.
-</para>
-</formalpara>
-
-<formalpara>
-<title><systemitem>--no-wintab</systemitem>,
- <systemitem>--ignore-wintab</systemitem></title>
-
-<para>
-Don't use the Wintab API for tablet support.
-</para>
-</formalpara>
-
-<formalpara>
-<title><systemitem>--use-wintab</systemitem></title>
-
-<para>
-Use the Wintab API for tablet support. This is the default.
-</para>
-</formalpara>
-
-<formalpara>
-<title><systemitem>--max-colors <replaceable>number</replaceable></systemitem></title>
-
-<para>
-In 256 color mode, restrict the size of the color palette to
-the specified number of colors. This option is obsolete.
-</para>
-</formalpara>
-
-</refsect2>
-
-<refsect2 id="win32-envar">
-<title>Windows-specific environment variables</title>
-
-<para>
-The Win32 GDK backend can be influenced with some
-additional environment variables.
-</para>
-
-<formalpara>
-<title><envar>GDK_IGNORE_WINTAB</envar></title>
-
-<para>
-If this variable is set, GTK doesn't use
-the Wintab API for tablet support.
-</para>
-</formalpara>
-
-<formalpara>
-<title><envar>GDK_USE_WINTAB</envar></title>
-
-<para>
-If this variable is set, GTK uses the Wintab API for
-tablet support. This is the default.
-</para>
-</formalpara>
-
-<formalpara>
-<title><envar>GDK_WIN32_MAX_COLORS</envar></title>
-
-<para>
-Specifies the size of the color palette used
-in 256 color mode.
-</para>
-</formalpara>
-
-</refsect2>
-
-<refsect2 id="win32-cursors">
-<title>Windows-specific handling of cursors</title>
-
-<para>
-By default the "system" cursor theme is used. This makes GTK prefer cursors
-that Windows currently uses, falling back to Adwaita cursors and (as the last
-resort) built-in X cursors.
-</para>
-<para>
-When any other cursor theme is used, GTK will prefer cursors from that theme,
-falling back to Windows cursors and built-in X cursors.
-</para>
-<para>
-Theme can be changed by setting <literal>gtk-cursor-theme-name</literal> GTK setting. Users can override GTK settings in the <filename>settings.ini</filename> file or at runtime in the GTK Inspector.
-</para>
-<para>
-Themes are loaded from normal Windows variants of the XDG locations:
-<filename>%HOME%/icons/THEME/cursors</filename>,
-<filename>%APPDATA%/icons/THEME/cursors</filename>,
-<filename>RUNTIME_PREFIX/share/icons/THEME/cursors</filename>.
-</para>
-<para>
-The <literal>gtk-cursor-theme-size</literal> setting is ignored, GTK will use the cursor size that Windows tells it to use.
-</para>
-
-</refsect2>
-
-<para>
-More information about GTK on Windows, including detailed build
-instructions, binary downloads, etc, can be found
-<ulink url="https://wiki.gnome.org/Projects/GTK/Win32">online</ulink>.
-</para>
-
-</refsect1>
-
-</refentry>
--- /dev/null
+<?xml version="1.0"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
+]>
+<refentry id="gtk-windows">
+<refmeta>
+<refentrytitle>Using GTK on Windows</refentrytitle>
+<manvolnum>3</manvolnum>
+<refmiscinfo>GTK Library</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+<refname>Using GTK on Windows</refname>
+<refpurpose>
+Windows-specific aspects of using GTK
+</refpurpose>
+</refnamediv>
+
+<refsect1>
+<title>Using GTK on Windows</title>
+
+<para>
+The Windows port of GTK is an implementation of GDK (and therefore GTK)
+on top of the Win32 API. When compiling GTK on Windows, this backend is
+the default.
+</para>
+
+<refsect2 id="win32-cmdline">
+<title>Windows-specific commandline options</title>
+
+<para>
+The Windows GDK backend can be influenced with some
+additional command line arguments.
+</para>
+
+<formalpara>
+<title><systemitem>--sync</systemitem></title>
+
+<para>
+Don't batch GDI requests. This might be a marginally useful option for
+debugging.
+</para>
+</formalpara>
+
+<formalpara>
+<title><systemitem>--no-wintab</systemitem>,
+ <systemitem>--ignore-wintab</systemitem></title>
+
+<para>
+Don't use the Wintab API for tablet support.
+</para>
+</formalpara>
+
+<formalpara>
+<title><systemitem>--use-wintab</systemitem></title>
+
+<para>
+Use the Wintab API for tablet support. This is the default.
+</para>
+</formalpara>
+
+<formalpara>
+<title><systemitem>--max-colors <replaceable>number</replaceable></systemitem></title>
+
+<para>
+In 256 color mode, restrict the size of the color palette to
+the specified number of colors. This option is obsolete.
+</para>
+</formalpara>
+
+</refsect2>
+
+<refsect2 id="win32-envar">
+<title>Windows-specific environment variables</title>
+
+<para>
+The Win32 GDK backend can be influenced with some
+additional environment variables.
+</para>
+
+<formalpara>
+<title><envar>GDK_IGNORE_WINTAB</envar></title>
+
+<para>
+If this variable is set, GTK doesn't use
+the Wintab API for tablet support.
+</para>
+</formalpara>
+
+<formalpara>
+<title><envar>GDK_USE_WINTAB</envar></title>
+
+<para>
+If this variable is set, GTK uses the Wintab API for
+tablet support. This is the default.
+</para>
+</formalpara>
+
+<formalpara>
+<title><envar>GDK_WIN32_MAX_COLORS</envar></title>
+
+<para>
+Specifies the size of the color palette used
+in 256 color mode.
+</para>
+</formalpara>
+
+</refsect2>
+
+<refsect2 id="win32-cursors">
+<title>Windows-specific handling of cursors</title>
+
+<para>
+By default the "system" cursor theme is used. This makes GTK prefer cursors
+that Windows currently uses, falling back to Adwaita cursors and (as the last
+resort) built-in X cursors.
+</para>
+<para>
+When any other cursor theme is used, GTK will prefer cursors from that theme,
+falling back to Windows cursors and built-in X cursors.
+</para>
+<para>
+Theme can be changed by setting <literal>gtk-cursor-theme-name</literal> GTK setting. Users can override GTK settings in the <filename>settings.ini</filename> file or at runtime in the GTK Inspector.
+</para>
+<para>
+Themes are loaded from normal Windows variants of the XDG locations:
+<filename>%HOME%/icons/THEME/cursors</filename>,
+<filename>%APPDATA%/icons/THEME/cursors</filename>,
+<filename>RUNTIME_PREFIX/share/icons/THEME/cursors</filename>.
+</para>
+<para>
+The <literal>gtk-cursor-theme-size</literal> setting is ignored, GTK will use the cursor size that Windows tells it to use.
+</para>
+
+</refsect2>
+
+<para>
+More information about GTK on Windows, including detailed build
+instructions, binary downloads, etc, can be found
+<ulink url="https://wiki.gnome.org/Projects/GTK/Win32">online</ulink>.
+</para>
+
+</refsect1>
+
+</refentry>
+++ /dev/null
-<?xml version="1.0"?>
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
- "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
-]>
-<refentry id="gtk-x11">
-<refmeta>
-<refentrytitle>Using GTK on the X Window System</refentrytitle>
-<manvolnum>3</manvolnum>
-<refmiscinfo>GTK Library</refmiscinfo>
-</refmeta>
-
-<refnamediv>
-<refname>Using GTK on the X Window System</refname>
-<refpurpose>
-X11-specific aspects of using GTK
-</refpurpose>
-</refnamediv>
-
-<refsect1>
-<title>GTK for the X Window System</title>
-
-<para>
-On UNIX, the X backend is the default build for GTK.
-So you don't need to do anything special when compiling it,
-and everything should "just work."
-</para>
-
-<para>
-To mix low-level Xlib routines into a GTK program,
-see <link linkend="gdk-X-Window-System-Interaction">GDK X Window
-System interaction</link> in the GDK manual.
-</para>
-
-<refsect2 id="x11-cmdline">
-<title>X11-specific commandline options</title>
-
-<para>
-The X backend understands some additional command line arguments.
-</para>
-
-<formalpara>
-<title><systemitem>--display <replaceable>display</replaceable></systemitem></title>
-
-<para>
-The name of the X display to open instead of the one specified
-in the <envar>DISPLAY</envar> environment variable.
-</para>
-</formalpara>
-
-</refsect2>
-
-<refsect2 id="x11-envar">
-<title>X11-specific environment variables</title>
-
-<para>
-The X11 GDK backend can be influenced with some additional environment variables.
-</para>
-
-<formalpara>
- <title><envar>GDK_SYNCHRONIZE</envar></title>
-
- <para>
- If set, GDK makes all X requests synchronously. This is a useful
- option for debugging, but it will slow down the performance considerably.
- </para>
-</formalpara>
-
-<formalpara>
- <title><envar>GDK_SCALE</envar></title>
-
- <para>
- Must be set to an integer, typically 2. If set, GDK will scale all
- windows by the specified factor. Scaled output is meant to be used on
- high-dpi displays. Normally, GDK will pick up a suitable scale factor
- for each monitor from the display system. This environment variable
- allows to override that.
- </para>
-</formalpara>
-
-</refsect2>
-
-</refsect1>
-
-<refsect1 id="gtk-X11-arch">
-<title>Understanding the X11 architecture</title>
-
-<para>
-People coming from a Windows or MacOS background often find certain
-aspects of the X Window System surprising. This section introduces
-some basic X concepts at a high level. For more details, the book most
-people use is called the <citetitle pubwork="book">Xlib Programming
-Manual</citetitle> by Adrian Nye; this book is volume one in the
-O'Reilly X Window System series.
-</para>
-<para>
-Standards are another important resource if you're poking in low-level
-X11 details, in particular the ICCCM and the Extended Window Manager
-Hints specifications. <ulink
-url="http://www.freedesktop.org/standards/">freedesktop.org</ulink>
-has links to many relevant specifications.
-</para>
-<para>
-The GDK manual covers <link
-linkend="gdk-X-Window-System-Interaction">using Xlib in a GTK
-program</link>.
-</para>
-
-<refsect2>
-<title>Server, client, window manager</title>
-
-<para>
-Other window systems typically put all their functionality in the
-application itself. With X, each application involves three different
-programs: the <firstterm>X server</firstterm>, the application (called
-a <firstterm>client</firstterm> because it's a client of the X
-server), and a special client called the <firstterm>window
-manager</firstterm>.
-</para>
-
-<para>
-The X server is in charge of managing resources, processing drawing
-requests, and dispatching events such as keyboard and mouse events to
-interested applications. So client applications can ask the X server
-to create a window, draw a circle, or move windows around.
-</para>
-
-<para>
-The window manager is in charge of rendering the frame or borders
-around windows; it also has final say on the size of each window,
-and window states such as minimized, maximized, and so forth.
-On Windows and MacOS the application handles most of this.
-On X11, if you wish to modify the window's state, or
-change its frame, you must ask the window manager to do so on your
-behalf, using an established <ulink
-url="http://www.freedesktop.org/standards/">convention</ulink>.
-</para>
-
-<para>
-GTK has functions for asking the window manager to do various things;
-see for example <link
-linkend="gtk-window-iconify">gtk_window_iconify()</link> or <link
-linkend="gtk-window-maximize">gtk_window_maximize()</link> or <link
-linkend="gtk-window-set-decorated">gtk_window_set_decorated()</link>.
-Keep in mind that most window managers <emphasis>will</emphasis> ignore
-certain requests from time to time, in the interests of good user interface.
-</para>
-
-<!--
-May also want to explain DESKTOP_STARTUP_ID here.
-http://www.freedesktop.org/Standards/startup-notification-spec
--->
-
-</refsect2>
-
-</refsect1>
-
-</refentry>
--- /dev/null
+<?xml version="1.0"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
+]>
+<refentry id="gtk-x11">
+<refmeta>
+<refentrytitle>Using GTK on the X Window System</refentrytitle>
+<manvolnum>3</manvolnum>
+<refmiscinfo>GTK Library</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+<refname>Using GTK on the X Window System</refname>
+<refpurpose>
+X11-specific aspects of using GTK
+</refpurpose>
+</refnamediv>
+
+<refsect1>
+<title>GTK for the X Window System</title>
+
+<para>
+On UNIX, the X backend is the default build for GTK.
+So you don't need to do anything special when compiling it,
+and everything should "just work."
+</para>
+
+<para>
+To mix low-level Xlib routines into a GTK program,
+see <link linkend="gdk-X-Window-System-Interaction">GDK X Window
+System interaction</link> in the GDK manual.
+</para>
+
+<refsect2 id="x11-cmdline">
+<title>X11-specific commandline options</title>
+
+<para>
+The X backend understands some additional command line arguments.
+</para>
+
+<formalpara>
+<title><systemitem>--display <replaceable>display</replaceable></systemitem></title>
+
+<para>
+The name of the X display to open instead of the one specified
+in the <envar>DISPLAY</envar> environment variable.
+</para>
+</formalpara>
+
+</refsect2>
+
+<refsect2 id="x11-envar">
+<title>X11-specific environment variables</title>
+
+<para>
+The X11 GDK backend can be influenced with some additional environment variables.
+</para>
+
+<formalpara>
+ <title><envar>GDK_SYNCHRONIZE</envar></title>
+
+ <para>
+ If set, GDK makes all X requests synchronously. This is a useful
+ option for debugging, but it will slow down the performance considerably.
+ </para>
+</formalpara>
+
+<formalpara>
+ <title><envar>GDK_SCALE</envar></title>
+
+ <para>
+ Must be set to an integer, typically 2. If set, GDK will scale all
+ windows by the specified factor. Scaled output is meant to be used on
+ high-dpi displays. Normally, GDK will pick up a suitable scale factor
+ for each monitor from the display system. This environment variable
+ allows to override that.
+ </para>
+</formalpara>
+
+</refsect2>
+
+</refsect1>
+
+<refsect1 id="gtk-X11-arch">
+<title>Understanding the X11 architecture</title>
+
+<para>
+People coming from a Windows or MacOS background often find certain
+aspects of the X Window System surprising. This section introduces
+some basic X concepts at a high level. For more details, the book most
+people use is called the <citetitle pubwork="book">Xlib Programming
+Manual</citetitle> by Adrian Nye; this book is volume one in the
+O'Reilly X Window System series.
+</para>
+<para>
+Standards are another important resource if you're poking in low-level
+X11 details, in particular the ICCCM and the Extended Window Manager
+Hints specifications. <ulink
+url="http://www.freedesktop.org/standards/">freedesktop.org</ulink>
+has links to many relevant specifications.
+</para>
+<para>
+The GDK manual covers <link
+linkend="gdk-X-Window-System-Interaction">using Xlib in a GTK
+program</link>.
+</para>
+
+<refsect2>
+<title>Server, client, window manager</title>
+
+<para>
+Other window systems typically put all their functionality in the
+application itself. With X, each application involves three different
+programs: the <firstterm>X server</firstterm>, the application (called
+a <firstterm>client</firstterm> because it's a client of the X
+server), and a special client called the <firstterm>window
+manager</firstterm>.
+</para>
+
+<para>
+The X server is in charge of managing resources, processing drawing
+requests, and dispatching events such as keyboard and mouse events to
+interested applications. So client applications can ask the X server
+to create a window, draw a circle, or move windows around.
+</para>
+
+<para>
+The window manager is in charge of rendering the frame or borders
+around windows; it also has final say on the size of each window,
+and window states such as minimized, maximized, and so forth.
+On Windows and MacOS the application handles most of this.
+On X11, if you wish to modify the window's state, or
+change its frame, you must ask the window manager to do so on your
+behalf, using an established <ulink
+url="http://www.freedesktop.org/standards/">convention</ulink>.
+</para>
+
+<para>
+GTK has functions for asking the window manager to do various things;
+see for example <link
+linkend="gtk-window-iconify">gtk_window_iconify()</link> or <link
+linkend="gtk-window-maximize">gtk_window_maximize()</link> or <link
+linkend="gtk-window-set-decorated">gtk_window_set_decorated()</link>.
+Keep in mind that most window managers <emphasis>will</emphasis> ignore
+certain requests from time to time, in the interests of good user interface.
+</para>
+
+<!--
+May also want to explain DESKTOP_STARTUP_ID here.
+http://www.freedesktop.org/Standards/startup-notification-spec
+-->
+
+</refsect2>
+
+</refsect1>
+
+</refentry>
projects / gtk4.git / commitdiff